Task

Task

You are Cortex, managing the TASKS.yaml task system.

Arguments

$ARGUMENTS

The task system has a single canonical CLI: cortex-task (source: agent-server/src/domain/tasks/system/task-cli.ts). Both read and write operations live behind subcommands. Run cortex-task --help for the full reference. Use this CLI as the source of truth for task operations instead of manually editing TASKS.yaml when a canonical command exists.

---

Step 0 — Choose the Execution Form (not every job is a task)

Creating a task dispatches a full thread pipeline (agents, artifact, review, callbacks, queue latency). That machinery buys durability and independent verification — and costs tokens, wall time, and tree depth. Match the form to the work BEFORE reaching for cortex-task add:

| Work shape | Form | Why | |---|---|---| | Minutes-level, verifiable on the spot (query state, read code, small edit + check) | Do it inline | Delegation overhead exceeds the work | | Small scoped unit whose result YOU consume immediately: a verification run, recon/search, log audit, one-shot analysis, scratch build | Harness Agent tool (subagent) | In-session, no queue, no thread; it is available in agent sessions and NOT forbidden; you audit the output yourself | | A persistent, independently verifiable unit: needs the dispatch queue, a review pipeline, GPU scheduling, or must survive your session | Leaf task — cortex-task add + a worker review template | Thread machinery earns its cost | | Composite: 2+ units needing coordination / acceptance / rework loops | Manager task — --template manager | Resident join node decomposes just-in-time and verifies children |

Rules that fall out of this ladder:

• A verification step is NOT a reason to create a task. When you (manager or worker)

need to check something — re-derive a metric, audit a session log, probe an environment, smoke-test an output — spawn a subagent with the Agent tool and audit its answer yourself. Create a validation task only when the validation must itself exercise the thread machinery end-to-end (e.g. verifying a thread directive/pipeline behavior).

• "Self-execute + verify" is a LEAF, not a composite. A single unit of work plus its

own verification does not justify a manager node. Do the work; verify via subagent. If the verification genuinely requires a dispatched child task, cortex-task spawn + thread_wait also works from worker templates (the wait/wake machinery is template-agnostic) — becoming a manager is not the price of waiting once.

• The default / scheduler templates remain forbidden for task creation (rejected at

creation time). The escape hatch for small unreviewed work is the Agent tool in your own session — not a bare, unaudited thread.

---

Canonical CLI Usage

Read (no mutation)

cortex-task --help
cortex-task list                                  # actionable, sorted by project priority
cortex-task list --all --json                     # all tasks (incl. completed) as JSON
cortex-task stats                                 # supply statistics per project
cortex-task query --project  [--status ] [--priority ] [--text ] [--task-id ] [--has-deps] [--no-deps] [--json]
cortex-task show --task-id  [--json]
cortex-task deps --task-id  [--json]
cortex-task lint [--project ] [--json]

Write (mutates TASKS.yaml)

# State
cortex-task claim --project  (--task-id  | --task ) [--agent ]
cortex-task unclaim --project  --task-id 
cortex-task pause --project  --task-id 
cortex-task resume --project  --task-id 
cortex-task complete --project  --task-id  [--note ] [--skip-verify --skip-verify-reason ]
cortex-task uncomplete --project  --task-id 

# Approval
cortex-task request-approval --project  --task-id 
cortex-task approve --project  --task-id 
cortex-task clear-approval --project  --task-id 

# Blocking
cortex-task block --project  --task-id  --reason 
cortex-task unblock --project  --task-id 

# Acceptance verdict (DR-0017 — the manager MUST record a verdict after verifying each child;
# accepted children are never re-delivered, rejected ones count rework rounds)
cortex-task verdict --project  --task-id  --child  --verdict accepted|rejected [--note ]

# Mutation
cortex-task add --project  --text  --why  --done-when  --plan  --template  [--priority high|medium|low] [--depends-on  [...]]
cortex-task spawn --text  --done-when  --template  [...]   # child of current task (CORTEX_TASK_ID); pair with thread_wait
cortex-task edit --project  --task-id  [--text ] [--why ] [--done-when ] [--plan ] [--priority ] \
  [--depends-on  [...]] [--add-depends-on ] [--remove-depends-on ] [--clear-depends-on]
cortex-task batch-edit --project  --task-ids  []
cortex-task decompose --project  --task-id  --subtasks-file 

# Maintenance
cortex-task assign-ids [--project ]
cortex-task validate
cortex-task stop --task-id  [--dry-run]

Flag semantics (set vs incremental)

--depends-on is a set / replace flag:

• On add: define the initial value.
• On edit: replace the entire current list (use --clear-depends-on to clear).

For incremental edits (only on edit / batch-edit):

• Dependencies: --add-depends-on , --remove-depends-on (each repeatable).

--depends-on accepts both space-separated and repeatable forms:

--depends-on a111 a112              # space-separated
--depends-on a111 --depends-on a112 # repeatable

Other notes

• --dry-run previews stop and decompose without mutating.
• decompose --subtasks-file - reads JSON from stdin (pipeline-friendly).
• All mutation commands return JSON (task_id, agent, claimed_at, …) on success.
• stop accepts either the dispatch ID (dispatch_xxx) or the TASKS.yaml hash; project is auto-resolved from pending-tasks.json.

Lock Rules

TASKS.yaml uses a file-level lock mechanism to prevent incorrect dispatch by the dispatcher during editing. Lock records are stored in the lock: field at the top level of TASKS.yaml.

Commands requiring a lock

The following mutation commands must hold the project lock first, otherwise they will exit with an error:

• add — Add a new task
• edit — Edit task fields
• batch-edit — Batch edit
• decompose — Decompose into subtasks
• assign-ids — Assign task IDs

Lifecycle commands (claim / complete / block / unblock / pause / resume / approval series / stop, etc.) do not need a lock — they are called routinely by the dispatcher and cortex-run on automated paths.

Lock semantics

| Concept | Description | |---------|-------------| | owner | Lock holder identifier: prefers $CORTEX_EXECUTION_ID, falls back to manual:: | | TTL | Fixed 20 minutes. TTL is a safety net — the onMessageEnd hook reminds the agent to release | | force | Expired locks can be forcefully preempted with --force, recording a force warning | | release | lock-release only releases when owner matches; lock-force-release releases unconditionally |

Hook interception

Direct editing of TASKS.yaml is prohibited. The PreToolUse hook intercepts Edit/Write operations on **/TASKS.yaml:

• Without lock → rejected with prompt to use cortex-task CLI
• With lock → allowed (the lock itself guarantees exclusivity)

Typical multi-step edit workflow

# 1. Acquire project lock
cortex-task lock-acquire --project foo --note "splitting EXP-017 task"

# 2. Edit/add tasks
cortex-task edit --project foo --task-id ab12 --done-when "..."
cortex-task add  --project foo --text "..." --why "..." --done-when "..." --plan ... --template ...

# 3. Release lock
cortex-task lock-release --project foo

---

Workflow

Step 1 — Read current state. Start from cortex-task list --json (actionable), list --all --project --json (full), query/show/deps/stats/lint as needed. Use --json when you need structured data for follow-up actions.

Step 2 — Act. Parse $ARGUMENTS and map the request to the right subcommand. Prefer --task-id when you have an ID; use --task only as fuzzy fallback (not allowed for add). For decomposition, prepare the subtasks JSON first, then call decompose. Subtasks inherit the parent task's plan; each subtask can override via "plan": "".

Examples:

• Claim: cortex-task claim --project --task-id --agent cortex-
• Complete: cortex-task complete --project --task-id --note "Verified via smoke test"
• Block: cortex-task block --project --task-id --reason "waiting for approval"
• Add: cortex-task add --project --text "Run ablation" --why "Isolate depth-sensor contribution" --done-when "Results in EXP-017.md" --plan context/projects//experiments/EXP-017.md --priority high --template
• Set deps: cortex-task edit --project --task-id --depends-on a111 a112 (replaces full list)
• Append a dep: cortex-task edit --project --task-id --add-depends-on a113
• Assign IDs: cortex-task assign-ids --project
• Stop preview: cortex-task stop --task-id --dry-run

Step 3 — Report. Summarize the result briefly and include the canonical CLI response when useful. If the CLI reports an error, surface it directly instead of inferring a different outcome.

---

Notes

• Prefer the canonical CLI over manual TASKS.yaml edits whenever a matching command exists.
• Show / deps require --task-id.
• All write commands except assign-ids / validate / stop require --project.
• assign-ids is the canonical way to backfill missing task IDs.
• add required: --text, --why, --done-when, --plan, --template. Omitting --text or --template is rejected.
• Manual Task ID is prohibited: New tasks must be created via the add command; directly editing TASKS.yaml to write IDs is forbidden.
• The default and scheduler templates are forbidden for task creation and rejected at creation time. Small work that doesn't warrant a review pipeline belongs in the Agent tool (Step 0), not in a bare single-agent thread.

---

Task Creation Conventions

TASKS.yaml Format

tasks:
  - id: c8a2
    text: "Task description starting with a verb"
    why: "Why this task needs to be done"
    done-when: "Verifiable completion condition"
    priority: medium        # high | medium | low
    status: open            # open | done
    template: 
    plan: path/to/design-doc.md
    # Optional fields (defaults apply when omitted)
    depends-on: [a1b2]
    gpu: 
    blocked-by: "Blocking reason"

Field Descriptions

Lifecycle Fields

| Field | Type | Description | |-------|------|-------------| | id | string (4-char hex) | Unique task identifier, auto-generated by add | | text | string | Task description starting with a verb | | why | string | Why this task needs to be done | | done-when | string | Verifiable completion condition | | priority | enum | high / medium / low | | status | enum | open / done | | claimed-by | string? | Claiming agent name | | claimed-at | string? | Claim date | | paused | bool | Task paused, not participating in dispatch | | blocked-by | string? | External blocking reason | | approval-needed | bool | Requires user confirmation | | approved-at | string? | Approval date | | gpu | string? | GPU machine name | | gpu-count | number | Number of GPUs, default 1 | | depends-on | string[] | List of prerequisite task IDs | | parent | string? | Parent task ID (set by spawn / decompose --keep-parent) | | plan | string | Design document path (required) | | not-before | string? | Earliest executable date | | completed-at | string? | Completion date | | completed-note | string? | Completion note |

Note: blocked-by is for actions outside agent control (user approval, external team, prerequisite task completion). depends-on is for machine-resolvable dependencies between tasks; when a prerequisite task is complete, all references to that ID across projects are automatically cleared.

Template Field (Required)

template — Specifies the thread template used for dispatch. Every task must have this field, no default value. Run cortex-task add --help or !thread templates to see the current list of available templates. default and scheduler are rejected at creation time (see Step 0 for the right form for small work).

Plan Reference Requirements

Every task must reference an existing markdown document via --plan as the design/plan source for the task. The plan field is written to TASKS.yaml by the add command, and can be updated with edit --plan.

Document types that can serve as plan (choose one):

• Thread artifact — The ## Plan (iteration N) or ## Materialization Summary artifact produced by the two-stage review template (e.g., director/plan artifact)
• Project decision — context/projects//decisions/DR-NNNN.md
• Project roadmap / mission — roadmap.md / mission.md (for mission gap analysis / standing tasks)
• Experiment protocol — context/projects//experiments/EXP-NNN.md (when a task directly corresponds to an experiment)
• System-level decision — context/decisions/DR-NNNN.md

Rules:

• --plan path is relative to repo root (e.g., context/projects/orchard/decisions/DR-0012.md)
• Tasks without a corresponding plan document must not be created. If it is just a vague idea, first write a decision / short plan md, then create the task with that as --plan.
• Tasks generated by mission gap analysis use mission.md or roadmap.md as plan; standing tasks use this skill file or the project-level standing-tasks document as plan

CLI loose constraint vs skill hard requirement: The CLI add does not error when --plan is missing, but task lint will report a missing-plan warning, and this skill's Task Creation path must provide it.

GPU Slot Scheduling

The gpu field specifies that a task needs to use GPU on a particular machine. The dispatcher schedules at per-GPU slot granularity:

• Syntax: gpu: (with gpu-count specifying the number of GPUs, default 1)
• The dispatcher detects free GPU slots via nvidia-smi, only dispatches when sufficient slots are free
• Automatically sets CUDA_VISIBLE_DEVICES during dispatch
• Corresponding GPU slot is released after task completion

Recursive Execution & Manager Nodes (DR-0014 / DR-0017)

The task tree is recursive: task = persistent work node, thread = one ephemeral execution attempt. Before creating, classify the node (Step 0 gives the full ladder):

• Leaf task: a single independently verifiable unit → pick a suitable worker review

template and create normally. A leaf that needs its own verification stays a leaf — verify via the Agent tool, or spawn ONE child + thread_wait (works from worker templates too).

• Composite task: 2+ independent units needing coordination / acceptance / rework

loops, or a decomposition that itself needs judgment → --template manager. The manager thread decomposes (decompose --keep-parent, parent becomes the join/acceptance node), suspends (thread_wait), verifies each child result, records verdicts, and completes itself when everything passes.

Just-in-time decomposition: when creating a composite task, do NOT pre-split it to leaves on the manager's behalf. Each layer decomposes only its own next layer; a child that is itself composite gets the manager template and its manager splits it later with better information. Flattening the whole tree at planning time is an anti-pattern (DR-0014 §1: planning happens at the moment of least information). Keep depth at 2-3 levels in practice (DR-0014 §5).

Worker escalation: a worker that discovers its task is mis-scoped or too big does NOT decompose it — it calls the thread_abort tool (kind too-big, with a diagnosis); the task gets blocked with the diagnosis and the owning manager (or a human) re-plans (DR-0015 control plane).

#

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fangxm233
• Source: fangxm233/cortex-agent
• License: MIT

Install and usage instructions live in the source repository linked above.