Amp Orb dots workflow

Amp-Orb-dots-workflow.md

Amp Orb dots workflow

Use this playbook when creating or updating another project's .agents/setup for Amp Orbs. Merge it into the existing setup; do not replace project-specific dependency or service setup.

1. Ensure Nix is available

Skip installation when nix already works. Otherwise install Determinate Nix non-interactively:

nix_profile=/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
if [ -f "$nix_profile" ]; then
  # shellcheck disable=SC1090
  source "$nix_profile"
fi
export PATH="/nix/var/nix/profiles/default/bin:$PATH"

if ! command -v nix >/dev/null 2>&1; then
  curl --proto '=https' --tlsv1.2 -sSfL \
    https://install.determinate.systems/nix \
    | sh -s -- install --no-confirm
  # shellcheck disable=SC1090
  source "$nix_profile"
  export PATH="/nix/var/nix/profiles/default/bin:$PATH"
fi

nix --version

2. Checkout dots with the Orb's GitHub credentials

The repository requires authenticated GitHub access. Do not put a token in a URL, Nix setting, script, or committed file.

dots_checkout="$HOME/.cache/towry-dots"
if [ ! -d "$dots_checkout/.git" ]; then
  gh repo clone towry/dots "$dots_checkout" -- --depth 1
else
  git -C "$dots_checkout" pull --ff-only
fi

3. Build the standalone Orb flake

Build the flake from the authenticated checkout instead of using a github: Nix URL:

orb_profiles_dir="$HOME/.local/state/nix/profiles"
profile="$orb_profiles_dir/dots-orb-workflow"
mkdir -p "$orb_profiles_dir"

nix build --profile "$profile" "path:$dots_checkout/nix/orb#default"
export PATH="$profile/bin:$PATH"
hash -r

The default profile provides just, jq, nixfmt, run-skill-script, shellcheck, uv, and vale. Keep the target project's own runtime and dependency setup alongside this workflow.

4. Persist the profile for resumed Orbs

orb_profile_script="$HOME/.config/dots/orb-profile.sh"
mkdir -p "$(dirname "$orb_profile_script")"
cat > "$orb_profile_script" <<'PROFILE_EOF'
profile="$HOME/.local/state/nix/profiles/dots-orb-workflow"
if [ -d "$profile/bin" ]; then
  export PATH="$profile/bin:$PATH"
fi
unset profile
PROFILE_EOF

profile_marker="# dots orb workflow profile"
if ! grep -Fqx "$profile_marker" "$HOME/.bash_profile" 2>/dev/null; then
  cat >> "$HOME/.bash_profile" <<'PROFILE_EOF'

# dots orb workflow profile
if [ -f "$HOME/.config/dots/orb-profile.sh" ]; then
  source "$HOME/.config/dots/orb-profile.sh"
fi
PROFILE_EOF
fi

5. Verify

Keep .agents/setup non-interactive and idempotent, then commit its executable bit:

chmod +x .agents/setup
./.agents/setup
./.agents/setup

/bin/bash -lc '
  command -v just
  command -v nixfmt
  command -v run-skill-script
  command -v shellcheck
  command -v uv
  command -v vale
'

Do not move dependency installation into .agents/resume; Amp runs .agents/setup for fresh project Orbs and reserves .agents/resume for fast wake-up repair.