aiworkhub_task_create
Creates a canonical repo-local task card defining write scope, acceptance criteria, validation commands, and dependencies so a worker can execute a scoped coding task.
Instructions
MANAGER WRITE: create one new canonical repo-local task card.
Creation choices (also exposed as field hints): difficulty: bounded, standard, complex (optional; never inferred). work_kind: generic, bugfix, refactor, performance, security, data_ml. validation_roles: generic, reproduction, regression, parity, baseline, delta, negative_fixture, schema, distribution, suite_vs_base; one per validation command. suite_vs_base: a pytest command that passes when every failing test also fails on the candidate's base. Required roles: bugfix=reproduction+regression; refactor=parity; performance=baseline+delta; security=negative_fixture; data_ml=schema+distribution. validation: shell-free executable commands; no environment assignments, pipes, redirects or chaining. Set environment outside validation argv. custom_template_escape: audited_custom_unclassified, explicitly audited unclassified cards only, not an automatic bypass; writable escaped cards require non-empty required_outputs covered by allowed_writes.
Replies with a creation receipt (aiworkhub.task_create_receipt.v1):
task_id, created/reconciled/receipt_state, scope_warnings, the
server-derived validation_roles, risk_tier/origin/signals,
difficulty/origin, validation_exemption, template_provenance, the
project_context
Source Graph query, and card_sha256/card_bytes -- never the card the
caller just typed. echo_card=True returns the full CLI envelope with
the persisted card in stdout instead. A refusal names every
violation at once (violations) with field, length and limit.
The live manager session supplies callback provider/origin identity;
callers cannot route a task into another chat, disable the mandatory
review callback, or overwrite an existing id.
depends_on (optional) names other task_ids in this repo that must
finish before this card is Plan-DAG ready; omit it for the pre-DAG
behavior.
Tasks are uncapped by default. Never infer, estimate, or auto-assign
max_live_tokens from task complexity, model, historical usage, or
cost. Supply it only when the owner explicitly requests an exact cap or a
repository policy pre-registers one. Process efficiency must come from
focused context, bounded reads, minimal edits, fewer retries, and useful
validation rather than from truncating work. An authorized cap is enforced
only when the selected provider exposes structured usage while running;
terminal-only usage remains posthoc evidence, never a false live-
enforcement claim.
A writable task's required_outputs may be empty ONLY when template
classification matches a contract that declares that default itself
(e.g. implementation_with_tests/cross_boundary_bugfix, whose
combined production+test scope keeps a deliberate empty default per
NF-2026-00456) or an explicit, in-scope mandatory list resolves that way.
Every other writable outcome -- including the audited custom-escape path,
which has no template contract of its own to fall back on -- requires a
non-empty required_outputs (NF-2026-00772); it contains only
repo-relative file paths or glob patterns covered by allowed_writes.
Human-readable outcome descriptions belong in acceptance; mixing
prose into required_outputs is rejected before a provider run is
launched.
allow_unchanged_required_outputs explicitly names required files that
are evidence inputs/outputs permitted to remain byte-identical to both
launch baselines; they are verified and hashed but never promoted.
allow_empty_required_outputs is the equivalent explicit exception for
deliberately zero-byte outputs. Neither exception is inferred.
read_only=True is required for a task that intentionally declares
both allowed_writes=[] and required_outputs=[]. Read-only intent is
never inferred from missing output authority.
runner is the worker execution identity returned by
aiworkhub_manager_workforce_rank.launch_contract.runner. The exact
value codex is reserved for the verified manager and is rejected for
worker cards.
work_kind is an explicit behavioral contract, never inferred from the
title or worker prose. Specialized values require one validation_roles
entry per validation command: bugfix=reproduction+regression,
refactor=parity, performance=baseline+delta, security=negative_fixture,
and data_ml=schema+distribution. Missing roles are rejected before launch.
suite_vs_base: a pytest command that passes when every failing test also
fails on the candidate's base.
risk_tier is optional explicit routing/economic evidence. It is never
inferred from priority or prose; omitted historical cards remain unknown.
It is a FLOOR: the observed write scope may escalate it, never lower it.
The skill_* fields are the card's skill selection vocabulary, drawn
from closed sets (aiworkhub_manager_skill_mine and
skill_registry.SELECTION_VOCABULARIES name them). An unknown token is
refused at create rather than silently matching nothing.
skill_task_family and skill_path_scope are derivable from the
template and the write set and may be omitted; skill_stage,
skill_triggers and skill_applicability are not derivable, and a
card that omits them selects no skill at all.
Default creation is template-first: generic Python production-plus-test
cards classify against the frozen registry, and unclassified raw cards
fail closed unless custom_template_escape is the audited token.
wave_goal_binding (optional) is exactly {roadmap_id, goal_id, predecessor_task_id} and makes this card that active wave goal's current
task in place of the predecessor. It is never inferred from a title,
topic, version suffix or prose; the receipt names its state.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"task_id": "<task_id>",
"title": "<title>",
"runner": "<runner>",
"topic": "<topic>",
"objective": "<objective>",
"acceptance": "<acceptance>",
"allowed_writes": "<allowed_writes>"
},
"name": "aiworkhub_task_create"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Short card title, 1-300 characters. | |
| topic | Yes | Topic that groups related cards: up to 128 characters, same character set as task_id. | |
| runner | Yes | Worker execution identity from aiworkhub_manager_workforce_rank launch_contract.runner; up to 128 characters, same character set as task_id. The value codex is reserved for the manager and rejected for worker cards. | |
| task_id | Yes | Unique card id: up to 256 characters of letters, digits, '_', '.', ':' or '-', starting with a letter or digit. An existing id is never overwritten. | |
| checkout | No | Worker tree checkout: sparse (default, declared closure only) or full (whole HEAD tree minus forbidden paths). Writes stay limited to allowed_writes either way. Refused with checkout_invalid:unknown_value:<value>. Omit for sparse. | |
| evidence | No | Optional supporting evidence for the worker (measurements, logs, reproduction notes), up to 16000 characters after stripping; tab/newline are kept, other control characters are refused. Stored on the card and placed in the worker's task contract after the objective. The objective keeps its own limit. Omit for none. | |
| priority | No | Scheduling priority: low, normal (default), high or critical. Case and surrounding space are normalized. | normal |
| deny_read | No | Up to 32 repo-style POSIX globs (*, ?, [..], ** segments; a glob without '/' matches a basename at any depth) whose matching files in the worktree and read_roots are made unreadable to the worker: a Landlock read layer on Linux, an explicit deny ACE on Windows AppContainer, refused on any other backend. Refused with deny_read_invalid:<reason>:<glob>. Omit for none. | |
| echo_card | No | Set true to return the full CLI envelope with the persisted card in stdout instead of the compact creation receipt. Default false. | |
| forbidden | No | Repo-relative paths or globs the worker must not touch, up to 128. A card whose writes, outputs, inputs, objective or validation overlap one is refused. Omit for none. | |
| objective | Yes | What the worker must achieve, 1-4000 characters. Naming a forbidden path here is refused as a contradiction. | |
| read_only | No | True for a card that deliberately writes nothing: allowed_writes and required_outputs must then both be empty. Never inferred; default false. | |
| risk_tier | No | Optional risk-tier floor: low, medium, high or critical. The observed write scope may raise it but never lower it. Omit to derive it from the scope. | |
| task_type | No | Card type: code (default; a writable code card must declare validation), data_classification or research. Case and surrounding space are normalized. | code |
| work_kind | No | Accepted work_kind values: generic, bugfix, refactor, performance, security, data_ml. Case and surrounding space are normalized by core; never infer from prose. | generic |
| acceptance | Yes | Acceptance criteria the finished work is reviewed against: 1-128 entries of up to 1000 characters each. Required. | |
| depends_on | No | Other task_ids in this repo that must finish before this card is Plan-DAG ready. Omit for no dependencies. | |
| difficulty | No | Accepted difficulty values: bounded, standard, complex. Optional; omitted remains undeclared, never inferred. Case and surrounding space are normalized by core. | |
| host_sweep | No | {tests: up to 512 pytest node ids or files, processes: int} run sharded on the full candidate tree, processes capped at the core count minus 25% headroom; a test red on base too is not a candidate failure. Refused with host_sweep_<field>_invalid. Omit for none. | |
| read_first | No | Repo-relative files the worker should read first, up to 128 entries of up to 1000 characters each. Omit for none. | |
| read_roots | No | Up to 16 absolute host directories OUTSIDE the worktree the provider worker may READ (runtime data), granted read-only on Windows AppContainer and Linux Landlock. Refused with read_root_invalid:<reason>:<path> when not an existing plain directory, or when it is a volume/UNC root, reparse point, .git/.aiworkhub path, the repo root or its parent, another git repository, the home directory or its credential folders. Omit for none. | |
| validation | No | shell-free executable commands, one per entry; no environment assignments, pipes, redirects, or command chaining. Set environment outside validation argv. | |
| materialize | No | Up to 64 repo-relative globs materialized (present, read-only by scope) in the sparse worker, validation and reproduction trees in addition to the declared closure, e.g. committed configs/models/eval data. Same path rules as allowed_writes; refused with materialize_invalid:<reason>:<value> when absolute, containing .. or .git, or too many. Writes stay limited to allowed_writes; forbidden paths are never materialized. Omit for none. | |
| skill_stage | No | Worker workflow stage to select skills for: orientation, implementation, validation, review or rework (not the card status); an unknown token is refused. Not derivable: omitting skill_stage, skill_triggers and skill_applicability selects no skill. | |
| host_commands | No | Up to 16 argv lists the coordinator runs in order on a FULL candidate tree after review_ready (same parser rules as validation commands, no env/cd prefixes). Files they create inside allowed_writes join the candidate; others are only reported. Refused with host_command_invalid:<index>:<reason>. Omit for none. | |
| allowed_writes | Yes | Repo-relative file paths or glob patterns the worker may write: up to 128 entries of up to 1000 characters each; absolute paths, '..' and directories are refused. Empty only together with read_only=true. | |
| skill_triggers | No | Observable conditions that make a skill relevant, from a closed vocabulary (e.g. code_change, public_api, security_sensitive, concurrency); at most 16, an unknown token is refused. Not derivable. | |
| max_live_tokens | No | Exact live-token cap (1-100000000), only when the owner explicitly requests one. Omit for uncapped; never estimate or infer a cap. | |
| immutable_inputs | No | Existing repo-relative files the worker may read but must not change. Omit for none. | |
| required_outputs | No | Repo-relative file paths or glob patterns the finished work must change, each covered by allowed_writes; up to 128. Put prose outcomes in acceptance, not here. Empty is accepted only for read_only cards or where the matched template contract defaults it empty. | |
| skill_path_scope | No | Repo-relative path or symbol that scopes skill selection; absolute paths and '..' are refused. Derivable from the write set, so it may be omitted. | |
| validation_roles | No | Accepted validation_roles: generic, reproduction, regression, parity, baseline, delta, negative_fixture, schema, distribution, suite_vs_base. Supply one role per validation command. Required: bugfix=reproduction+regression; refactor=parity; performance=baseline+delta; security=negative_fixture; data_ml=schema+distribution. Case and surrounding space are normalized by core. suite_vs_base: a pytest command that passes when every failing test also fails on the candidate's base. | |
| skill_task_family | No | Skill family: analysis, bugfix, data_ml, docs, implementation, performance, refactor, replay, security or test; an unknown token is refused. Derivable from the template and the write set, so it may be omitted. | |
| wave_goal_binding | No | Exactly {roadmap_id, goal_id, predecessor_task_id}: makes this card the active wave goal's current task in place of the predecessor. Never inferred; a malformed binding is refused. Omit for none. | |
| skill_applicability | No | Surface kinds a skill applies to, from a closed vocabulary (e.g. quality_gate, public_api_surface, security_surface, storage_schema_surface); at most 16, an unknown token is refused. Not derivable. | |
| apply_contract_patch | No | sha256 digest of a contract patch a finalizer already published; it supplies allow_unchanged_required_outputs by reference and is never applied automatically. Naming both the digest and allow_unchanged_required_outputs is refused. Omit for none. | |
| custom_template_escape | No | Explicit audited escape token: audited_custom_unclassified. Only for deliberately audited unclassified cards, not an automatic bypass. Writable escaped cards require non-empty required_outputs covered by allowed_writes. | |
| allow_empty_required_outputs | No | Exact repo-relative paths (no globs) of required outputs that may deliberately end up zero bytes, each covered by required_outputs and allowed_writes. Never inferred. | |
| allow_unchanged_required_outputs | No | Exact repo-relative paths (no globs) of required outputs that may stay byte-identical to both launch baselines, each listed exactly in required_outputs and allowed_writes. Never inferred; use apply_contract_patch instead to name them by digest, never both. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||