Write scripts to check PROJECT.md staleness and launch agent commands

[williamthorsen]

Problem

Developers must manually check whether .agents/PROJECT.md is out of date before starting an AI agent session. This requires scanning commit history and comparing dates — tedious and easy to forget. A stale PROJECT.md means the agent works with outdated context.

Context

The update-project-guidance skill refreshes PROJECT.md, but nothing tells the developer when to run it. The assess-ticket skill has a similar staleness model for tickets, but PROJECT.md has no equivalent.

The agents package already has shell scripts in packages/agents/scripts/ for development tooling. These new scripts serve a different purpose (end-user utilities) but live alongside them.

Solution

Shell scripts (in packages/agents/scripts/)

1. check-project-staleness.sh — standalone staleness heuristic. Checks whether .agents/PROJECT.md exists in the current git repo and, if so, counts meaningful commits since its last modification. Commits that only touch package manifests and lock files (**/package.json, **/pnpm-lock.yaml, **/package-lock.json, **/yarn.lock) are excluded. If the count reaches 20, prints a warning to stderr and suggests running /update-project-guidance. Always exits 0.

2. claude.sh — launcher that runs the staleness check, then execs claude with all arguments forwarded.

3. rovo.sh — launcher that runs the staleness check, then execs acli rovodev run with all arguments forwarded.

4. install-launchers.sh — symlinks the other three scripts into a target directory (default /usr/local/bin). Accepts --prefix to override the target.

All scripts follow the project's shell conventions: set -euo pipefail, main() wrapper, show_usage with proper exit codes, $PROG prefix on error messages. Symlink-safe resolution to locate check-project-staleness.sh relative to the launcher.

Warning output format (stderr):

⚠️ PROJECT.md may be stale:
  Last updated: 2025-10-19 10:31 UTC (5 months ago)
  Since then:   47 commits
  Run /update-project-guidance to refresh it

Root pnpm scripts

Add convenience scripts to the monorepo root package.json:

• agents:install — runs the agents CLI install command (tsx packages/agents/src/cli.ts install)
• agents:install-launchers — runs install-launchers.sh

Acceptance criteria

• check-project-staleness.sh exits silently when not in a git repo, when .agents/PROJECT.md is absent, or when the file has no git history
• check-project-staleness.sh excludes commits that only touch package/lock files from the count
• check-project-staleness.sh prints the warning (with ⚠️) to stderr when the threshold (20) is met, and always exits 0
• claude.sh runs the staleness check and forwards all arguments to claude
• rovo.sh runs the staleness check and forwards all arguments to acli rovodev run
• install-launchers.sh symlinks all three scripts into the target directory (default /usr/local/bin, overridable with --prefix)
• All scripts include --help with usage, arguments, options, and examples per shell conventions
• All scripts pass shellcheck
• Root package.json has agents:install and agents:install-launchers scripts