# Task

> MUST Use when adding, editing, querying, or managing cortex tasks — includes the execution-form triage (inline vs Agent-tool subagent vs task vs manager), task creation conventions (format, tagging, decomposition rules). MUST use before using cortex-task CLI.

- **Type:** Skill
- **Install:** `agentstack add skill-fangxm233-cortex-agent-task`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fangxm233](https://agentstack.voostack.com/s/fangxm233)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [fangxm233](https://github.com/fangxm233)
- **Source:** https://github.com/fangxm233/cortex-agent/tree/main/agent-server/defaults/plugins/cortex-stage-gate/skills/task

## Install

```sh
agentstack add skill-fangxm233-cortex-agent-task
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)

```bash
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)

```bash
# 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:
```bash
--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

```bash
# 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

```yaml
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](https://github.com/fangxm233)
- **Source:** [fangxm233/cortex-agent](https://github.com/fangxm233/cortex-agent)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-fangxm233-cortex-agent-task
- Seller: https://agentstack.voostack.com/s/fangxm233
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.