AlexandrAI AGENTS.md
agents-md

Personal Work Agent Bootstrap Installer Agent Guide

Project-specific AGENTS.md guidance for Personal Work Agent bootstrap scripts, platform steps, doctor checks, shell linting, cron setup, and tests.

AGENTS.md

Guidance for coding agents working on Personal Work Agent bootstrap and installer scripts.

Project Overview

The bootstrap directory installs or verifies the local runtime environment through shell steps for platform detection, system packages, Python, uv, Codex, project environment, keyring, verification, and cron. The Makefile lints shell files with bash syntax checks and optional shellcheck.

Use this boundary when changing install.sh, doctor.sh, step runner behavior, platform detection, cron setup, or docs under docs/bootstrap.

Project Map

  • scripts/bootstrap/install.sh is the installation entry point.
  • scripts/bootstrap/doctor.sh verifies the environment.
  • scripts/bootstrap/lib/common.sh, os_detect.sh, and step_runner.sh provide shared shell helpers.
  • scripts/bootstrap/steps/ contains ordered setup phases for Linux, macOS, WSL, system packages, Python, uv, Codex, project env, keyring, verify, and cron.
  • docs/bootstrap/ and docs/install.md document user-facing setup and troubleshooting.
  • Makefile runs bash syntax validation and optional shellcheck over bootstrap shell files.
  • tests/test_bootstrap_contract.py, test_bootstrap_scripts.py, test_bootstrap_platform_steps.py, and test_bootstrap_runtime_contract.py cover bootstrap behavior.

Setup Commands

bashmake lint
uv run pytest tests/test_bootstrap_contract.py tests/test_bootstrap_scripts.py -q
uv run pytest tests/test_bootstrap_platform_steps.py tests/test_bootstrap_runtime_contract.py -q

Change Rules For Agents

  • Keep shell steps idempotent and safe to rerun.
  • Preserve step ordering and naming conventions because tests assert contracts.
  • Validate shell syntax for every changed script.
  • Keep platform-specific logic in platform step files, not in shared helpers.
  • Do not embed machine-specific paths, private credentials, or user-local tokens in scripts or docs.
  • Update docs/bootstrap when installer behavior changes.
  • Prefer explicit failure messages over silent fallback.

Verification

bashmake lint
uv run pytest tests/test_bootstrap_scripts.py tests/test_bootstrap_contract.py -q

Manually review changed shell scripts for quoting and command substitution safety.

Security Notes

Install scripts run on user machines. Avoid unsafe eval, unquoted variables, hidden network assumptions, and credential echoing. Keep secrets out of logs and docs.

PR Checklist

  • Shell scripts pass bash syntax checks.
  • Bootstrap contract tests pass.
  • Docs reflect changed setup behavior.
  • Steps remain idempotent and platform-scoped.