Files
warp/script/bootstrap
Zach Lloyd b84e3e98d9 Add opt-in common skills installer (#10121)
## Description
Replaces the custom common-skills lock file with the standard project
lock generated by `npx skills`, and wires local setup to restore
checked-in common skills from that lock.

This PR:
- Removes `.agents/common-skills.lock` and the custom common-skills
lock/update workflow.
- Adds `skills-lock.json`, the standard `npx skills` project lock for
skills sourced from `warpdotdev/common-skills`.
- Keeps the copied `.agents/skills/*` files checked in so local and
cloud agents can discover repo-local skills directly from the checkout.
- Reworks `script/install_common_skills` to restore from
`skills-lock.json` via `npx --yes skills@1.5.6 experimental_install`.
- Stores the local install stamp under
`.git/warp/common-skills-lock.hash` so normal restores do not dirty the
worktree.
- Updates `script/run` to check the lock before building and restore
skills only when the lock hash changed.
- Keeps `./script/bootstrap --install-common-skills` and
`.\script\windows\bootstrap.ps1 -InstallCommonSkills` as explicit
bootstrap paths that delegate to the same installer.
- Adds `specs/common-skills-installation/TECH.md` with separate Mermaid
diagrams for the local install/update flow and the Oz Claude cloud-agent
environment setup flow.

Pretty cool loom of what's coming on orchestration for anyone interested
:)

https://www.loom.com/share/87212dc5a6824573861794e32cf9902d

## Flow
### Local agent install/update flow
1. `warpdotdev/warp` checks in both `skills-lock.json` and
`.agents/skills/*`.
2. `script/run` calls `script/install_common_skills --if-needed
--non-interactive --quiet` before launching the local build.
3. The installer hashes `skills-lock.json` and compares it with
`.git/warp/common-skills-lock.hash`.
4. If the hash matches, it skips restore and continues the build.
5. If the hash is missing or stale, it runs `npx --yes skills@1.5.6
experimental_install`, restores `.agents/skills/*` with the pinned
`skills@1.5.6` CLI, writes the new local stamp, and then continues.
6. To intentionally update common skills, run `npx --yes skills@1.5.6
update -p -y` and commit the resulting `skills-lock.json` and
`.agents/skills/*` changes together.

### Oz Claude cloud-agent environment setup flow
1. Oz provisions or reuses a cloud environment and clones/syncs
`warpdotdev/warp`.
2. Environment setup should invoke `./script/install_common_skills
--if-needed` after checkout sync and before starting the Claude agent.
3. Fresh environments restore from `skills-lock.json`; reused
environments skip when the cloud-local stamp matches.
4. The Claude agent starts with repo-local checked-in skills
discoverable, and runs may still pass explicit skill specs such as
`warpdotdev/warp:create-pr`.

The Oz environment hook itself lives outside this repo; this PR makes
the repository checkout self-sufficient and idempotent when that hook
invokes the installer.

## Linked Issue
- [ ] The linked issue is labeled `ready-to-spec` or
`ready-to-implement`.
- [ ] Where appropriate, screenshots or a short video of the
implementation are included below (especially for user-visible or UI
changes).

## Screenshots / Videos
Not applicable; script/docs/skills change.

## Testing
- `bash -n script/install_common_skills script/run script/bootstrap`
- PowerShell parse check for `script/windows/bootstrap.ps1`
- `./script/install_common_skills --if-needed --quiet` using pinned
`skills@1.5.6`
- second `./script/install_common_skills --if-needed --quiet` skip-path
check
- `git diff --check`
- Earlier branch validation: `cargo check --manifest-path Cargo.toml`
- Earlier branch validation: `cargo fmt --all --manifest-path
Cargo.toml`
- Earlier branch validation: `cargo clippy --manifest-path Cargo.toml
--workspace --all-targets --all-features --tests -- -D warnings`

## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode

Co-Authored-By: Oz <oz-agent@warp.dev>

---------

Co-authored-by: Oz <oz-agent@warp.dev>
2026-05-09 19:20:01 +00:00

101 lines
3.0 KiB
Bash
Executable File

#!/usr/bin/env bash
set -eo pipefail
# Bootstrap dispatches to the platform-specific install scripts. Each step
# that needs root sources `script/warp_sudo` and asks for confirmation
# before running. Pass -y / --yes (or set WARP_SKIP_SUDO_PROMPT=1) to skip
# the prompts in unattended environments.
OS_TYPE="$(uname -s)"
INSTALL_COMMON_SKILLS=0
PLATFORM_ARGS=()
usage() {
cat <<EOF
Usage: ./script/bootstrap [options]
Prepare this checkout for Warp development by running the platform-specific bootstrap steps.
Options:
-h, --help Show this help message.
--install-common-skills Install or update common agent skills from skills-lock.json.
Environment:
WARP_SKIP_COMMON_SKILLS_INSTALL=1
Skip installing common agent skills, even when --install-common-skills is provided.
EOF
}
print_bootstrap_preview() {
local platform="$1"
echo "Warp bootstrap is starting for ${platform}."
echo "It will:"
if [[ "${platform}" = "macOS" ]]; then
echo " - Configure Xcode as the active developer directory."
echo " - Install or update Cargo, Homebrew, PowerShell, Docker, gcloud, and related development tools."
echo " - Add the aarch64-apple-darwin Rust target."
elif [[ "${platform}" = "Linux" ]]; then
echo " - Update apt package metadata."
echo " - Install dependencies needed to build, run, and test Warp."
echo " - Install linuxdeploy and check gcloud authentication."
fi
if [[ "${INSTALL_COMMON_SKILLS}" -eq 0 ]]; then
echo " - Skip common agent skills unless --install-common-skills is provided."
elif [[ "${WARP_SKIP_COMMON_SKILLS_INSTALL:-}" = "1" ]]; then
echo " - Skip common agent skills because WARP_SKIP_COMMON_SKILLS_INSTALL=1."
else
echo " - Install or update common agent skills from skills-lock.json if needed."
fi
echo "Run ./script/bootstrap --help to see options and environment overrides."
echo
}
for arg in "$@"; do
case "${arg}" in
-h|--help)
usage
exit 0
;;
-y|--yes)
export WARP_SKIP_SUDO_PROMPT=1
if [[ ! "$OS_TYPE" =~ ^(MINGW64_NT|MSYS_NT) ]]; then
PLATFORM_ARGS+=("${arg}")
fi
;;
--install-common-skills)
INSTALL_COMMON_SKILLS=1
;;
*)
PLATFORM_ARGS+=("${arg}")
;;
esac
done
maybe_install_common_skills() {
if [[ "${INSTALL_COMMON_SKILLS}" -eq 1 ]]; then
./script/install_common_skills --if-needed
fi
}
if [[ "$OS_TYPE" = "Darwin" ]]; then
print_bootstrap_preview "macOS"
./script/macos/bootstrap "${PLATFORM_ARGS[@]}"
maybe_install_common_skills
elif [[ "$OS_TYPE" = "Linux" ]]; then
print_bootstrap_preview "Linux"
./script/linux/bootstrap "${PLATFORM_ARGS[@]}"
maybe_install_common_skills
elif [[ "$OS_TYPE" =~ ^(MINGW64_NT|MSYS_NT) ]]; then
if [[ "${INSTALL_COMMON_SKILLS}" -eq 1 ]]; then
./script/windows/bootstrap.ps1 "${PLATFORM_ARGS[@]}" -InstallCommonSkills
else
./script/windows/bootstrap.ps1 "${PLATFORM_ARGS[@]}"
fi
else
echo "No bootstrap script defined for the current platform!"
exit 1
fi