Taskmaster Cheat Sheet 🛠️

Canonical SSOT: ssot.0rk.de/plans/omp-extensions/omptask

Zero-bloat. No MCP. No DB. Just pure native YAML-driven power. 🚀

🏗️ 1. ARCHITECTURE IN A NUTSHELL

• State: .taskmaster/tasks.yml (Single Source of Truth 📄)
• Extension: ~/.omp/agent/extensions/taskmaster.ts (Native TS via Jiti ⚡)
• Runtime: @earendil-works/pi-coding-agent (v0.79+)

🪝 2. THE HOLY TRINITY API

1. Context Injection: pi.on("before_agent_start", ...) ➡️ Returns { systemPrompt }. NEVER mutate event.systemPrompt directly; append and return.
2. LLM Tools: pi.registerTool({ name, parameters, execute }) ➡️ Uses TypeBox & StringEnum.
3. Human Commands: pi.registerCommand("tm", ...) ➡️ Read-only UI summary via ctx.ui.notify().

🚦 3. STATE MACHINE (tasks.yml)

tasks:
  - id: 1
    title: "Overstand Everything"
    status: pending # 🚦 pending | in-progress | done | blocked | deferred | cancelled
    priority: high # 🔥 high | medium | low
    deps: [] # 🔗 unblocks when ALL deps are 'done'/'cancelled'

🛠️ 4. THE task TOOL ACTIONS

• 📥 parse_prd: Ingests docs/prd.md headings/bullets natively.
• 🎯 next: Returns highest priority, unblocked task.
• ➕ add / 🔄 update: Create or mark tasks done (auto-unlocks deps!).
• 🪓 expand: Breaks heavy tasks into chewable subtasks inline.
• 📜 list: Dumps the whole backlog.

🧠 5. GOLDEN RULES (OMP INVARIANTS)

• 🛡️ Zero-Crashing: Catch all I/O errors. Missing YAML? Return empty array silently.
• 🛑 No ctx.logger: It doesn’t exist on this API version. Use ctx.ui.notify(msg, "info").
• 🧩 StringEnum Mandatory: Type.Union breaks Google APIs. Use StringEnum from @earendil-works/pi-ai.
• 🔄 Stateless by Design: Re-read tasks.yml every call to prevent async cross-agent state corruption.

Always Be Looping. 😇