Skip to content

AGENTS.md

Latest commit

 

History

History
56 lines (47 loc) · 3.04 KB

AGENTS.md

File metadata and controls

56 lines (47 loc) · 3.04 KB
Raw

AGENTS.md — bootstrap directive for a fresh pi agent

You are a fresh pi agent running inside the pi-power-stack repo. The user cloned this repo and opened pi here to install a full power-user environment onto this machine. When the user says "set it up" (or anything equivalent), follow the procedure below. Do the work yourself with your tools — read, then run the commands, verify, and report.

What this repo is

A complete, portable Pi power-user setup: custom extensions, a 25-tool suite, sub-agents, 17 skills, multi-provider config (Claude Max + Codex Max primary), a global operating doctrine, and an optional Overstory multi-agent orchestration tier. Full inventory in ARCHITECTURE.md.

The "set it up" procedure

Execute these in order. The authoritative, detailed version is SETUP.md — read it fully first, then execute. Summary:

  1. Preflight. Confirm pi, node (20+), git exist. If pi is missing, tell the user to run npm install -g @earendil-works/pi-coding-agent and stop until it's present.
  2. Run the installer. From the repo root: 
    chmod +x install.sh scripts/*.sh doctor.sh
./install.sh
    It backs up any existing ~/.pi/agent config (timestamped), deploys everything, installs npm/pi packages, and installs the orchestration tier to ~/pi-orchestration/.
  3. Report what changed, then hand off the login step to the user — you cannot do OAuth for them. Tell them to run, in a new pi session: 
    /login anthropic        → Claude Max (browser OAuth)
/login openai-codex     → Codex Max (browser OAuth)
/model anthropic/claude-opus-4-8
  4. Verify. Run ./doctor.sh and summarize pass/fail. Fix anything red that is fixable without credentials (missing dirs, unexecutable scripts, missing npm deps).
  5. Point them at the docs: README.md (overview), ARCHITECTURE.md (every component), orchestration/RUNBOOK.md (the swarm), and the newly-installed ~/.pi/agent/AGENTS.md (their global doctrine — tell them to edit the workspace root + GitHub account to taste).

Hard rules while setting up

  • Never fabricate success. If a step fails, say so and show the error. A working setup with three honest warnings beats a "done!" that doesn't run.
  • Secrets are the user's. This repo ships ZERO credentials by design. Do not invent API keys or tokens. Logins are interactive and done by the user.
  • Idempotent & reversible. install.sh backs up before overwriting. If the user already had a pi config, tell them where the .bak-* backups are.
  • Patches are opt-in. Do NOT run --with-patches unless the user asks; they are version-fragile package customizations and the stack works fully without them.
  • This is macOS-first (built/tested on macOS + Ghostty). On Linux most of it works; flag macOS-specific bits (sips, pbcopy, Ghostty) if the user is on Linux.

Once installed, this bootstrap file stops mattering — the user's real operating doctrine is ~/.pi/agent/AGENTS.md (a copy of pi/AGENTS.md from this repo).