using-xtrm

name	using-xtrm
description	Behavioral operating manual for an xtrm-equipped Claude Code session. Covers when to use which tool, how to handle questions and triggers, workflow examples, and skill routing. Reference material (hook list, gate rules, full bd commands, git workflow) lives in CLAUDE.md. Injected automatically at session start via additionalSystemPrompt.
priority	high

XTRM — When to Use What

Gates, commands, and git workflow are in CLAUDE.md. This is the behavioral layer: triggers, patterns, examples.

Session Start

bd prime                          # load workflow context + active claims
bd memories <today's topic>       # retrieve relevant past context
bv --robot-triage                 # graph-ranked picks, quick wins, unblock targets
bd update <id> --claim            # claim before any edit

Use bv --robot-next for the single top pick. Use bv --robot-triage --format toon to save context tokens. Never run bare bv — it launches an interactive TUI.

---

Current xt Command Surfaces

Use these command surfaces when the task is operational rather than code-editing:

Need	Command	Notes
Refresh xtrm-managed skills/hooks/reports in one repo	xt update --apply	Default xt update is dry-run; --apply writes. Also reports bd/GitNexus maintenance and applies the bd auto-stage patch.
Refresh many repos under a root	xt update --apply --root <dir>	Discovers repos with .xtrm/registry.json; failures are reported per repo.
Sweep standard local fleet	xt update --all-repos then xt update --apply --all-repos	Scans ~/dev + ~/projects; dry-run first. Apply patches and commits each changed repo.
Cut a release	xt release prepare --patch then xt release publish	prepare drafts from xt reports; publish tags/pushes. If prepare fails on changelog script compatibility, check specialists unitAI-dnmcg state and use the manual fallback in /releasing.
Close a session report	update latest same-day .xtrm/reports/<date>-*.md	session-close-report prefers one same-day SSOT handoff; do not create duplicate reports unless asked.

Worktree dependency setup

xt claude / xt pi sessions use clean git worktrees. Git does not copy ignored dependency artifacts such as node_modules/, .venv/, build caches, or generated outputs. If a repo's lint/tests need those files, run the repo's normal bootstrap inside the worktree (make bootstrap, just setup, npm ci, uv sync, etc.). Do not track dependency directories to make worktrees pass.

Multi-pane coordination

Route orchestrators to /multiplexing and delegated panes to /multiplexing-team. A beaded xtmux message-send requires a reply unless it explicitly says --expects-reply=false.

For reply-required inbound work, preserve the SQLite messageKey, acknowledge receipt, then use message-reply --in-reply-to <messageKey>; ack or a target/bead-matched send does not fulfil it. If the reply must also wake a pane, use confirmed safe-send-pointer --reply-to <messageKey> so fulfilment happens only after injection succeeds.

SQLite owns obligations and waits across restarts. Recover with obligations list, monitor-list, and message-status; never create or delete runtime marker files. Runtime identities and ownership come from the invoking live tmux session/pane, not message text or caller-supplied metadata.

---

Trigger Patterns

Situation	Action
User prompt contains ?	bd memories <keywords> before answering — check stored context first
"What should I work on?"	bv --robot-triage — ranked picks with dependency context
"What was I working on?"	bd list --status=in_progress
Unfamiliar area of code	gitnexus_query({query: "concept"}) before opening any file
About to edit a symbol	gitnexus_impact({target: "name", direction: "upstream"})
Before git commit	gitnexus_detect_changes({scope: "staged"}) to verify scope
About to bd create a bead for a specialist dispatch	Add --parent <bead-it-services> (nests .1, recursive .1.1) + title <role>: <task> — never a loose top-level bead
About to dispatch a specialist (sp run)	bd state <id> contract — if draft or unset, promote first (explore + rewrite full contract + bd set-state <id> contract=ready); never dispatch against a draft
Just capturing an idea for later, not working it now	bd create --labels contract:draft with a real PROBLEM + rough SCOPE, everything else TBD — never a one-liner
Coordinating tmux panes or handling a reply-required xtmux message	/multiplexing (or /multiplexing-team when delegated); preserve and correlate the returned messageKey
Reading code	get_symbols_overview → find_symbol — never read whole files
Task is tests	use /test-planning
Task is docs updates	use /sync-docs
Session end (issue closed)	Memory gate fires — evaluate bd remember for each closed issue

---

Handling ? Prompts

When the user's message contains a question, check stored context before answering:

bd memories <keywords from question>   # search project memory
bd recall <key>                        # retrieve specific memory if key is known

Example — user asks "why does the quality gate run twice?":

bd memories "quality gate"
# → "quality-check.cjs and quality-check.py are separate hooks —
#    JS/TS and Python each get their own PostToolUse pass"

If it's a code question, also run:

gitnexus_query({query: "<topic>"})     # find relevant execution flows

---

Workflow Examples

Fixing a bug:

bd ready                                                        # find the issue
bd update bd-xyz --claim                                        # claim it
gitnexus_impact({target: "parseComposeServices", direction: "upstream"})
# → 2 callers, LOW risk — safe to edit
sed -n '<start>,<end>p' hooks/init.ts                            # targeted read
# Apply the verified edit with the runtime's native edit tool.
bd close bd-xyz --reason="Fix YAML parse edge case"            # close issue
xt end                                                         # push, PR, merge, cleanup

Exploring unfamiliar code:

gitnexus_query({query: "session claim enforcement"})
# → beads-gate-core.mjs, resolveClaimAndWorkState, decideCommitGate
gitnexus_context({name: "resolveClaimAndWorkState"})            # callers + callees
sed -n '<start>,<end>p' hooks/beads-gate-core.mjs                # targeted read

Persisting an insight:

bd remember "quality-check runs twice: separate .cjs (JS) and .py (Python) hooks"
# retrievable next session:
bd memories "quality check"
bd recall "quality-check-runs-twice-..."

---

Prompt Shaping (silent, before every non-trivial task)

Task type	Apply
analyze / investigate / why	<thinking> block + structured <outputs>
implement / build / fix	1-2 <example> blocks + <constraints>
refactor / simplify	<constraints> (preserve behavior, tests pass) + <current_state>

Vague prompt (under 8 words, no specifics)? Ask one clarifying question before proceeding.

---

Skill Routing

Need	Use
Code read / edit	GitNexus context/query, then targeted reads and native edit tools
Blast radius before edit	gitnexus-impact-analysis
Navigate unfamiliar code	gitnexus-exploring
Trace a bug	gitnexus-debugging
Safe rename / refactor	gitnexus-refactoring
Docs maintenance	sync-docs
Docker service project	using-service-skills
Build / improve a skill	skill-creator
Orchestrate tmux panes / answer correlated requests	multiplexing / multiplexing-team