apra-labs/apra-fleet/fleet

Fleet Skill

This skill defines how to interact with fleet infrastructure: registering and onboarding members, managing permissions, dispatching work, monitoring tasks, and handling provider-specific differences.

Core Fleet Tools

See sub-documents for detailed usage:

• onboarding.md - full 8-step member onboarding sequence
• permissions.md - permission composition and denial handling
• profiles/ - stack permission profiles (base-dev, base-reviewer, node, python, go, etc.) - add new profiles here to support additional stacks or roles
• troubleshooting.md - fleet tool troubleshooting by symptom
• skill-matrix.md - skill installation matrix by project + VCS + role
• auth-github.md, auth-bitbucket.md, auth-azdevops.md - VCS auth provisioning per provider
• beads.md - Beads persistent task DB: commands, backlog ops, session recovery patterns
• beads-conflict-resolution.md - manual dolt SQL recovery when bd dolt pull/push reports a real merge conflict

Beads - Persistent Task Tracking

Beads (bd CLI) is installed automatically by apra-fleet install. It gives fleet users a persistent, dependency-aware task database that survives across sessions, branches, and members.

Run `bd` via `Bash` on the orchestrator - never via `execute_command` on a member.

See beads.md for the full command reference and workflow examples.

Secret variables

The {{secret.NAME}} pattern lets you reference stored secrets in any command without ever exposing plaintext to the LLM or logs.

How it works:

1. Store a secret with credential_store_set - Fleet opens an OOB terminal prompt, so the value never appears in chat
2. Reference it as {{secret.NAME}} anywhere in a command string passed to execute_command, register_member, update_member, provision_vcs_auth, provision_llm_auth, or setup_git_app
3. Fleet resolves the token server-side before execution; LLM does not see the secret.

When to use:

• Any API key, token, or password that a member needs in a shell command
• Rotating credentials: credential_store_delete then credential_store_set - no re-provisioning required
• Pre-loading secrets before a dispatch so members can authenticate in commands autonomously

NOTE: `{{secret.NAME}}` only resolves in specific credential fields (listed above). Using it in any other parameter (e.g. a prompt, a path field in a non-credential tool, or any other unsupported parameter) will pass the token string through literally - the secret will NOT be injected, and the raw handle name will be visible in logs. Only use {{secret.NAME}} in the fields documented above.

Access control (scoping): Credentials can be scoped to specific members.

• members="*" (default) - all members can access the credential
• members="alice,bob" - only those members can access it
• Scoping is enforced at resolve time - a member outside the allowed set receives an access-denied error
• Updating scope or metadata: Use credential_store_update to change members, ttl_seconds, or network_policy without re-entering the secret. Use credential_store_set again only if you need to change the secret value (triggers OOB re-entry).

TTL (time-to-live): Set ttl_seconds to auto-expire a credential. Expired credentials are rejected at resolve time with a clear error (not silently empty).

Example: credential_store_set name=ci_token ttl_seconds=3600

Network egress policy: Attach a network policy to a credential to control outbound network access for commands that use it:

Member Identification

All tools accept member_id (UUID) or member_name (friendly name) to identify a member. member_id takes precedence when both are provided.

Tool Boundaries

• Local members: ALWAYS use fleet tools (execute_command, execute_prompt, send_files, etc.) - never SSH directly or bypass fleet infrastructure
• Fleet tools are the canonical interface - all member interactions go through them

Dispatch Rules

Rule: Shell commands (git, npm, bash scripts, file ops) -> execute_command. LLM reasoning tasks (write code, review, plan, analyse) -> execute_prompt. When in doubt: if a human could write the exact command string upfront, it's execute_command.

• `execute_prompt` - always wrap in a background Agent: Agent(run_in_background=true). No exceptions.
• `execute_command` - any command that may take several seconds must be wrapped in a background Agent. Short reads (cat, git status, echo) can be called inline. Always use bash syntax - Git Bash is universally available on developer machines. Never use PowerShell or cmd.exe syntax, even on Windows members.
• When clubbing fleet calls into a background Agent: Always name the tool explicitly in the subagent prompt - write "use execute_command to run..." or "use execute_prompt to dispatch...". Never leave tool selection implicit.
• `send_files` / `receive_files` - transfers exceeding 1MB must use a background Agent.

Concurrent dispatch guard: Only one execute_prompt can be in-flight per member at a time (enforced server-side). A second concurrent dispatch returns immediately with:

x execute_prompt is already running for "<member-name>"

Use stop_prompt to cancel the in-flight session before re-dispatching.

Pre-dispatch Checks

Before dispatching any work:

1. fleet_status - confirm member is idle (status must not be busy)
2. Member must have completed onboarding - see onboarding.md

Do not dispatch to a busy member. If busy, wait or re-check member_detail.

File Transfer

Both send_files and receive_files are batch operations - always transfer all files in a single call, never one file per call.

• send_files - push any files to a member: context files, plans, scripts, binaries, configs, or any other content. Takes local_paths (array of local file paths) and optional dest_subdir (destination subdirectory relative to work_folder on member; defaults to work_folder root, equivalent to "."). Optional substitutions: { name: value } replaces every {{name}} token in each file before transfer - see Substitutions section below. Always try to batch multiple files in a single call.
• receive_files - pull files back: results, logs, build artifacts, updated configs, etc. Takes remote_paths (array of file paths on the member) and local_dest_dir (local directory to write files into). Always try to batch multiple files in a single call.

Directories and globs: send_files accepts individual file paths only - directories and glob patterns are not supported yet. To transfer an entire directory, tar it locally and extract on the member:

1. execute_command on local: tar -czf /tmp/src.tar.gz -C /path/to src/
2. send_files: local_paths=["/tmp/src.tar.gz"]
3. execute_command on member: tar -xzf src.tar.gz && rm src.tar.gz

Cross-OS transfers: Both send_files and receive_files work bidirectionally for Linux<->Windows transfers (fleet host on Linux, member on Windows, and vice versa).

Substitutions (send_files and execute_prompt)

Both send_files and execute_prompt accept an optional substitutions: { "token_name": "value" } parameter that replaces {{token_name}} placeholders in file content or prompt text before the content is delivered to the member.

Usage:

send_files(
  local_paths=["docs/sprint-briefing.md"],
  substitutions={ branch: "feat/task-1", base_branch: "main", member_name: "Alice" }
)
 
execute_prompt(
  member=...,
  prompt="Continue Phase {{phase}}. Branch: {{branch}}.",
  substitutions={ phase: "3", branch: "feat/task-1" }
)

Rules:

• Token names must match [A-Za-z_][A-Za-z0-9_]* - no dots, hyphens, or other special characters.
• All tokens used in any file (or the prompt string) must have a corresponding key in substitutions. Missing tokens cause the call to fail with zero side effects (no files written, no CLI invoked).
• Extra keys are silently ignored - pass a superset map without error.
• No recursive substitution: values containing {{...}} are written verbatim.
• Source files on the fleet host are never modified; only the delivered copy is substituted.
• If substitutions is omitted and file/prompt content contains {{token}} patterns, a warning is returned (call still succeeds).

[SECURE] Secrets boundary -- never use substitutions for secrets:

• Substitution keys with dots (e.g. secret.github_pat) are rejected outright.
• {{secret.NAME}} patterns in file/prompt content pass through verbatim - they are resolved later only by execute_command via the credential store, not here.
• Substitution values are never logged. But callers must not put plaintext secrets in substitution values; use {{secret.NAME}} in execute_command for secrets.

Permissions

compose_permissions produces provider-native config automatically. See permissions.md for:

• How to compose and deliver permissions before dispatching work
• How to handle permission denials during execution
• How to recompose when switching roles

execute_prompt Parameters

execute_prompt accepts substitutions (see Substitutions section above), model, resume, and timeout parameters.

Timeout Parameters

execute_prompt accepts two independent timeout parameters: