/create-item

name: create-item
description: "Creates an MCP work item from conversation context. Scans existing containers to anchor the item in the right place (Bugs, Features, Tech Debt, Observations, etc.), infers type and priority, creates single items or work trees, and pre-fills required notes. Use when the conversation surfaces a bug, feature idea, tech debt item, or observation worth tracking persistently. Also use when user says: track this, log this bug, create a task for, or add this to the backlog."
argument-hint: "[optional: brief description of what to create]"

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:

| Pattern | Classification | |---------|---------------| | Depth-0 item with category-named children (Bugs, Features, etc.) | **Hierarchical** — project root exists | | Category-named items at depth 0, no project root | **Flat** — use category containers directly | | No items at all | **Empty** — offer to create project root |

---

Step 3 — Container anchoring

Category mapping

| Item type | Target category container | Signal keywords | |-----------|--------------------------|-----------------| | Bug / error / crash / unexpected behavior | Bugs | bug, error, crash, broken, failure, wrong, exception | | Feature / enhancement / new capability | Features | feature, add, implement, new, support, capability, enhancement | | Tech debt / refactor / cleanup / improvement | Tech Debt | refactor, cleanup, simplify, debt, improve, migrate, restructure | | Observation / friction / optimization / missing capability | Observations | slow, performance, optimize, latency, friction, missing, gap, observe | | Action item / follow-up / reminder / TODO | Action Items | todo, follow up, remind, action, track, check | | General / unclear | Best-effort match — ask if uncertain | |

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 —