Skip to main content
ship-tasks is the single CyberOS workflow that drives every unit of work from specification to delivery. There is no separate workflow for net-new features versus hardening or fixes — all work goes through the same machinery. A class: product task and a class: improvement task follow identical lifecycle rules, share one BACKLOG.md, and both require the same two mandatory human-acceptance gates. The workflow lives in .cyberos/cuo/ship-tasks.md inside any CyberOS-initialised repo and is also bundled inside the /ship-tasks plugin skill.

​
The 10 task states

A task carries exactly one status at any point in time. The states form a single linear lifecycle with two off-ramps. The authoritative definition of all states lives in .cyberos/cuo/STATUS-REFERENCE.md.

​
The BACKLOG.md index

docs/tasks/BACKLOG.md is the single index for all work. One file covers every module and every class of task — there is never a second backlog file. To add a task, append one row in your module’s section:
For class: improvement tasks, add the (improvement) tag:
The task file’s status: frontmatter field is the record of truth. BACKLOG.md is the index kept in lockstep with it. Never update one without updating the other.

​
How the agent picks tasks

When you trigger ship-tasks, the agent:
  1. Reads BACKLOG.md and finds all tasks with status: ready_to_implement
  2. Filters out tasks whose depends_on list contains any task not yet in done
  3. Picks the first eligible task (by order in BACKLOG.md)
  4. Moves it to implementing and begins work
If no eligible tasks exist, the agent reports the block and stops. Check depends_on fields and the status of dependency tasks if this happens.

​
Failure and routing back

There are no terminal failure states in the CyberOS lifecycle. When a task fails at any in-cycle step, the workflow routes it back:
  • The task status returns to ready_to_implement
  • routed_back_count in the task frontmatter increments by 1
  • The reason is recorded in an audit row
On the next ship-tasks run, the task is picked up again from the start. The routed_back_count field is your signal that a task has looped — if it is high, the spec or the implementation approach may need rethinking.

​
Gates

Gates are the machine verification layer between implementation and human review. They must be green before the agent can request your review at either human gate. Your repo’s gate commands are stored in .cyberos/gates.env and run with:
The installer auto-detects your build, lint, and test commands and writes them to gates.env. Edit that file if the auto-detected commands are wrong. A standard gates.env looks like:
Gates run automatically as part of ship-tasks. You can also run them manually at any time to check repo health.
ship-tasks is agent-independent — the same workflow, the same gate runner, and the same two human gates work with Claude, Codex, Cursor, Gemini, Grok, or any agent that can read files and run shell commands. Point the agent at AGENTS.md or .cyberos/AGENT-ENTRY.md and it drives the workflow correctly.

Human Gates

Understand exactly what to check at Gate 1 and Gate 2, and how to approve or route back.

Ship Your First Task

Step-by-step walkthrough from writing a task file to landing the finished change.