Agent Blu Tools**

Lifecycle class: governed execution interface.
Authority: Bluefly Runtime Governance.
Rule: Tools do not create authority. Tools execute only inside authorized scope.

Agent Blu must prefer existing Bluefly command surfaces over improvised shell logic.

Tool authority order

blu-cli
→ gt
→ bd
→ qmd
→ context-control-cli
→ agent-buildkit
→ repo-native tools
→ shell primitives

Do not jump to lower-level tools when an authoritative higher-level command exists.

Primary operator CLIs

blu-cli

Bluefly operator facade.

Use for:

• Gas Town orchestration
• governed receipts
• evidence capture
• platform runtime workflows
• operator-safe wrappers
• cross-system coordination

Never replace blu-cli with ad hoc scripts when a canonical command exists.

gt

Gas Town runtime surface.

Use for:

• gt prime
• runtime identity
• orchestration status
• convoys
• nudges
• mail
• escalation
• Dolt runtime health

gt is runtime orchestration, not policy authority.

bd

Beads issue and durable task-state surface.

Use for:

• task ownership
• work state
• issue lifecycle
• durable execution tracking

Do not use markdown TODOs, TodoWrite, or duplicate task ledgers when bd is available.

qmd

Directive and doctrine retrieval surface.

Use for:

• operating doctrine lookup
• architectural memory
• prior decisions
• packet rules
• lane boundaries

Query before making governance decisions.

context-control-cli

ContextControl operational CLI.

Use for:

• tenant operations
• memory operations
• context diagnostics
• authority workflows
• ContextControl runtime checks

agent-buildkit

Repeatable engineering execution surface.

Use for:

• workspace validation
• repo hygiene
• agent workflows
• build/test/release operations
• deterministic engineering tasks

Prefer agent-buildkit over one-off shell workflows when it provides the operation.

Engineering tools

Expected local tools:

git
glab
ddev
drush
docker
composer
npm
node
jq
yq
rg
fd
curl
lsof
uv
python via uv

glab is the official GitLab CLI surface for working with GitLab issues, merge requests, pipelines, and related project workflows from the terminal.  

ddev is the local web-development environment surface; use ddev exec for commands inside project containers and ddev help/ddev help <command> for command discovery.  

drush is the Drupal command-line and scripting interface for installing, developing, debugging, and maintaining Drupal sites.  

uv is the Python package/project manager surface. In ClawX sessions, prefer uv run python <script> and uv pip install <package> over bare python or pip; uv documents both Python management and pip-compatible package installation.  

Tool selection rules

1. Check tool availability before claiming limitation.
2. Prefer canonical CLIs over improvised shell.
3. Prefer repo-native scripts over manual command sequences.
4. Prefer GitLab APIs or glab for MR, pipeline, approval, and issue state.
5. Prefer ddev/drush for Drupal runtime inspection.
6. Prefer uv for Python execution in ClawX.
7. Prefer jq/yq for structured data inspection.
8. Prefer rg/fd for search and path discovery.
9. Use shell primitives only when no higher authority exists.
10. Never create a new script folder to compensate for an existing tool.

Mutation rules

Read operations are safe by default.

Mutations require:

identity verified
repo verified
branch verified
path ownership verified
bead or explicit no-bead reason
Cedar/policy posture checked
packet scope confirmed
stop condition known

Destructive actions require explicit approval.

Forbidden without explicit packet:

git push
git add -f
git reset
git clean
git stash
force push
branch rewrite
rm -rf
manual Dolt filesystem edits
manual SQL repair
Cloudflare mutation
Tailscale mutation
Oracle mutation
NAS runtime mutation
secret/profile edits

Git discipline

Before commit:

git status --short
git diff --cached --name-only
git diff --cached --stat
verify branch
verify staged files exactly match packet scope

A commit records the current Git index, so contaminated staging must be treated as a blocker, not a warning.  

GitLab discipline

Use glab or GitLab UI/API for:

MR state
approval state
pipeline status
conflicts
labels
review blockers
merge readiness

Do not infer MR open/closed/mergeable state from Git refs alone.

Drupal discipline

Use:

ddev status
ddev describe
ddev exec vendor/bin/drush status
ddev exec vendor/bin/drush cr
ddev exec vendor/bin/drush config:status
ddev exec vendor/bin/drush pm:list
composer validate
composer show

Never hand-edit Composer-managed Drupal code.
Never bypass config schema.
Never claim installability without Drupal runtime validation.

ClawX tool notes

Python

Use:

uv run python <script>
uv pip install <package>

Do not use bare python or pip unless explicitly required by the runtime and verified.

Browser

Use the managed browser when asked to inspect, search, test, scrape, fill forms, or interact with a live page.

Flow:

start
→ snapshot
→ act

Use element refs from snapshots. Retry once for transient browser/network failures. Do not substitute training data when live lookup was requested.

Failure behavior

If a required tool is missing, return:

COMMAND_GAP

If a tool exists but policy blocks it, return:

POLICY_GAP

If the tool would mutate outside scope, return:

AUTHORIZATION_REQUIRED

If multiple tools claim the same authority, return:

DRIFT_DETECTED

Golden rule

Use the highest-authority existing tool that can safely complete the task.

Do not invent a new operational path.

ClawX Tool Notes

uv (Python)

• uv is bundled with ClawX and on PATH. Do NOT use bare python or pip.
• Run scripts: uv run python <script> | Install packages: uv pip install <package>

Browser

• browser tool provides full automation (scraping, form filling, testing) via an isolated managed browser.
• Flow: action="start" → action="snapshot" (see page + get element refs like e12) → action="act" (click/type using refs).
• Open new tabs: action="open" with targetUrl.
• To just open a URL for the user to view, use shell:openExternal instead.
• If a browser action fails, transient errors (timeout, network) can often be resolved by retrying once or navigating to a different URL.
• When asked to search, look up, or interact with a web page, use the browser tool. Do not substitute with guesses or training data when real-time web access is requested.