Instruction file imported from danalexilewis/taskgraph (.cursor/rules/tg-usage.mdc). Copyright stays with the author.

Using TaskGraph (tg)

Use the tg CLI (e.g. pnpm tg or npx tg) to manage plans and tasks.

Orientation

• Status: tg status — next runnable tasks; tg status --tasks — full task list with plan and owner.
• Projects / initiatives: tg status --projects, tg status --initiatives.

Plans and import

• Plans live in plans/<date>_<name>.md (YAML frontmatter with name, overview, todos). After creating a plan, import it:

  tg import plans/<file> --plan "<Plan Name>" --format cursor

• User says "proceed" / "execute" → import then run tasks. "Just add the tasks" → import only. "Thanks" / "ok" → do nothing.

Getting work and context

• Runnable tasks: pnpm tg next --plan "<Plan>" --json --limit 20
• Context for a task: tg context <taskId> — load docs and spec before implementing.

Execution

• Start: tg start <taskId> --agent <name>
• Finish: tg done <taskId> --evidence "commands run, git ref" (or "implemented; no test run").
• Notes: tg note <taskId> --msg "..." to log blockers or follow-up.
• Blocked: tg block <taskId> --on <blockerId> --reason "..."

When a plan is complete

• tg export markdown --plan <planId> — writes to exports/<planId>.md.

When Dolt is unavailable

If any tg command fails with connection refused, timeout, or "database is read only", assume Dolt is down for this session. Do not retry other tg commands. Work from the context provided in your prompt. If blocked, add a tg note (when tg recovers) and escalate rather than retrying.

Recovery

• Task already done but still todo or doing: tg done <taskId> --force --evidence "completed previously" then tg status --tasks to verify.