Task Orchestrator Item Creator

create-item — Container-Anchored Work Item Creation

Create MCP work items intelligently from conversation context. This skill handles container anchoring, tag inference, structure decisions, and note pre-population so you don't have to.

Step 1 — Infer intent from conversation

Determine from context (or from $ARGUMENTS if provided):

• Title — what is the work item?
• Type — bug / feature / tech debt / observation / action item / general task
• Priority — high / medium / low (default: medium)
• Scope — single item, or feature with 2+ clear distinct subtasks?

If title or type cannot be inferred with confidence, use AskUserQuestion with concrete options. Do not ask open-ended questions.

Step 2 — Scan containers

Resolve the scope first from the SessionStart context. A ## Project Scope section (Active project plus a Config: line) carries a project rootId: it scopes reads and anchors new root-level items. A ## Personal Scope section (Personal root plus a Config: line) carries a personal root: it only anchors new items, and reads stay unscoped (no ancestorId/anchorId on read calls, which may show other projects' items). Without session context, read .taskorchestrator/config.yaml's top-level project.rootId (a file read, not an MCP call), which yields a project rootId only.

If a project rootId is known:

query_items(operation="overview", anchorId="<rootId>", includeChildren=true)

Category containers (Bugs, Features, Tech Debt, etc.) are expected as direct children of the project root — anchor new items there. Exception: agent-observation items always stay at global depth 0, outside any project root, regardless of whether a rootId is known — they're process-global, not project-scoped.

If a personal root is known: the anchor-finding scan may run under it (query_items(operation="overview", anchorId="<personal root>", includeChildren=true)) — that finds an anchor, it does not read work. If no container there fits, create the item with parentId=<personal root>; never leave it at depth 0.

If no rootId is known, fall back to an unscoped scan and the classification below (this is also the exact behavior from before project scoping existed):

query_items(operation="overview", includeChildren=true)

Classify the existing structure:

Step 3 — Container anchoring

Category mapping

Anchoring decision tree

Hierarchical structure:
  Matching category found under project root → use as parentId
  Category missing under project root → create it, then use as parentId

Flat structure:
  Matching category at depth 0 → use as parentId
  Category missing at depth 0 → create it, then use as parentId

Empty (no project root exists):
  → AskUserQuestion: "No project root container exists yet.
    Would you like to create one for this project?"
  → Yes: create project root → create category under it → create item
  → No: create category container at depth 0 → create item under it

Exception (all branches): agent-observation items never anchor under a project root or category container — they are standalone process-global items (each its own root, not a child of any container) that live at depth 0 alongside (not under) any project root, per Step 2.

Step 4 — Set type via schema discovery

Read the file named by the session context's Config: line when there is one, otherwise .taskorchestrator/config.yaml, to discover available schemas (this is a file read, not an MCP call). In Docker, the config is mounted at a path controlled by the AGENT_CONFIG_DIR env var — read $AGENT_CONFIG_DIR/.taskorchestrator/config.yaml if that variable is set, otherwise use .taskorchestrator/config.yaml relative to the working directory.

Schemas are defined under work_item_schemas: (preferred) or note_schemas: (legacy). Each schema key is a type identifier that activates gate enforcement when set as the item's type field. Tags remain available for categorization but are no longer the primary schema selector.

Error handling: If the config file is not found, cannot be read, or contains invalid YAML, skip schema-based type assignment and create the item without a type. Inform the user: "No schema config found — item created without a type." Do not abort item creation due to a missing or malformed config.

Infer the best schema match from context:

If the inferred schema key exists in the config, set it as the item's type value. If the key does not exist in the config (e.g., no bug-fix schema defined), leave type unset — do not assign a type that has no matching schema.

When no confident match can be inferred:

• If a schema named default exists in the config, use it as the fallback — this lets users control what happens to unclassified items
• Otherwise, ask the user which schema to apply via AskUserQuestion, listing the available schema keys from the config
• Include a "No schema" option for items that should be schema-free

If no config file exists, skip type assignment entirely — all items will be schema-free.

Tags vs. type: Set type for schema selection. Use tags only for additional categorization/filtering that is independent of schema matching.

Trait discovery

While reading the config, also check for a top-level traits: section. Each key under traits: is a trait name that can be assigned to items via the traits parameter. Traits add additional note requirements on top of the base schema.

Assess whether any configured traits apply based on conversation context:

Only assign traits that exist in the config. If no traits: section exists, skip trait assignment entirely.

If multiple traits apply, combine them: traits: "needs-migration-review,needs-api-compat-review"

Resource-bearing traits (informational): if a chosen trait's config entry carries its own resources: list, note this to the user — items with that trait will acquire an exclusive lease on the named resource key(s) when they enter work phase, and advance_item(start) can transiently fail with resource_unavailable if another item currently holds it. No extra action is needed here; this is just so the choice isn't a surprise later.

Step 5 — Create the item(s)

Dedup check first. Before creating each item (a work tree's root only — its children inherit the check), run ONE unscoped search:

query_items(operation="search", query="<title key terms>", limit=5)

It stays unscoped even when a rootId is known: depth-0 process-global items such as agent-observations sit outside any project ancestor, so an ancestorId-scoped search misses them. Show close matches as one FYI line (role + short id each) and let the user decide — never auto-link, auto-skip or auto-cancel.

Single item (bug, observation, standalone task, action item):

manage_items(operation="create", items=[{
  title: "<inferred title>",
  summary: "<1-2 sentence description from context>",
  priority: "<inferred priority>",
  type: "<schema key or omit>",
  tags: "<categorization tags or omit>",
  parentId: "<category container UUID>"
  // Additional fields like `complexity` are optional — omit if not relevant
}])

Work tree (feature with 2+ distinct subtasks clearly described):

create_work_tree(
  root={title, summary, priority, type: "<schema key>"},
  children=[{ref: "t1", title: "..."}, {ref: "t2", title: "..."}, ...],
  parentId="<category container UUID>"
)

Default to single item when scope is unclear. Use create_work_tree only when the conversation explicitly names multiple distinct subtasks.