using-termcanvas

name	using-termcanvas
description	Use when starting work in a TermCanvas-managed repo to route between direct work, Hydra, or a narrow TermCanvas skill.
alwaysApply	true

Using TermCanvas

Route first. Choose the lightest path that preserves correctness.

Routing

• If the user wants to challenge, stress-test, or critically review an idea, argument, or proposal, use challenge.
• If the user asks to investigate a bug, debug, or diagnose an issue, use investigate.
• If the user asks for a security review or audit, use security-audit.
• If the user asks for a code review or diff review, use code-review.
• If the user asks to test a site, QA a page, or verify a deploy, use qa.
• If the task is simple, local, high-certainty, or faster in the current agent, do it directly. Do not invoke Hydra by default.
• If the task needs an isolated worktree, file evidence, retry/status control, or a staged workflow, use hydra.
• Before using Hydra in a repo, ensure the project has current Hydra instructions via hydra init-repo or the TermCanvas Hydra enable action.

Hydra workflow patterns

Lead-driven, decision-point oriented. The Lead reads the codebase, picks the strategy, and dispatches workers for the steps that need a fresh agent process. Roles available: lead (the decider — not itself dispatched), dev (writes code AND its tests), reviewer (independent cross-model check). No separate researcher — the Lead does its own research. No separate tester — dev owns its own test surface.

• hydra init --intent "..." --repo . then dispatch dev -> reviewer for ambiguous, risky, or PRD-driven work
  • call hydra watch after each dispatch to wait for the decision point
• hydra spawn --task "..." --repo . for a single isolated worker
  • use when the task split is already known and you do not need the full Lead-driven loop

Hydra worker primitive

• hydra spawn --task "..." --repo .
  • one direct isolated worker terminal
  • use when the task split is already known and you do not need a full workflow

Guardrails

• Do not describe Hydra workflows as automatic parallelism unless multiple spawned workers are actually involved.
• When launching Claude/Codex tasks via TermCanvas CLI, use termcanvas terminal create --prompt "..." rather than termcanvas terminal input.
• After hydra dispatch, immediately start hydra watch — do not ask whether to watch.
• Use hydra watch / hydra status / hydra ledger / hydra list --workflows for workflows created by hydra init.
• Use hydra list and hydra cleanup <agentId> for direct workers created by hydra spawn.
• Prefer structured Hydra state and files over terminal prose.

Memory Graph

When the session context contains a <memory-graph> block from TermCanvas:

• Check "References" before reading a memory file — referenced files are likely also relevant, follow the links
• If a memory is marked "Time-sensitive" with a date that has clearly passed, verify its content against current project state before acting on it
• Do not cite memory-graph metadata to the user — it's for your navigation, not for display