ServicesTask Service
Task Definition and Action Contracts
task.md schema, when trigger semantics, and action contracts
Task Definition and Action Contracts
Task definition file
.ship/task/<taskId>/task.mdtaskId is derived from normalized title, and title should stay unique.
Frontmatter fields
| Field | Required | Description |
|---|---|---|
title | Yes | Unique task name |
description | Yes | Goal description |
contextId | Yes | Execution context id |
when | Yes | Trigger: @manual / cron / time:ISO8601 |
status | Yes | enabled / paused / disabled |
kind | No | agent (default) or script |
when semantics
@manual: manual trigger only.- cron expression: periodic scheduling.
time:2026-03-08T10:30:00+08:00: one-shot trigger (timezone required).
After one-shot execution succeeds:
status -> pausedwhen -> @manual
Actions
| Action | Purpose | Key response |
|---|---|---|
list | list task definitions | tasks[] |
create | create task definition | may return reusedExisting=true |
update | update definition | writes task.md |
run | manual run once | returns accepted=true + executionId immediately |
status | explicit status set | enabled/paused/disabled |
enable/disable | status shortcuts | same as status update |
delete | remove definition and run history | returns task dir path |
Create de-dup logic
create now deduplicates by exact title only:
- same
titleexists: reuse existing task (reusedExisting=true) - otherwise: create a new task
No semantic-similarity dedup is applied.
run contract
run is async-accepted:
- verify task exists
- start
runTaskNow(...)in background - return immediately with
accepted=true,message, andexecutionId
Additional agent rule:
- success requires successful
chat_senddelivery - delivery failure is treated as
executionStatus=failure
CLI and API
CLI:
city task run daily-check --reason "manual"API:
city service command task run --payload '{"title":"daily-check","reason":"manual"}'