# Verify Bot Foundry

> Verifies Pi Bot Foundry through its real CLI and generated Bot surface. Use after changing botctl, the Bot contract, templates, validation, or launch behavior.

- Skill: `ythx-101/verify-bot-foundry` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add ythx-101/verify-bot-foundry`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ythx-101/verify-bot-foundry/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ythx-101 (https://skillmd.com/u/ythx-101)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ythx-101/verify-bot-foundry

---


# Verify Pi Bot Foundry

## Launch

This is a short-lived CLI. No server stays running. From the repository root, run each drive in a fresh process:

```bash
python3 scripts/botctl.py --help
```

For the full deterministic pass:

```bash
python3 scripts/verify_foundry.py
```

Add `--live` only when Pi credentials and runtime access are available.

## Doctor

Run these read-only checks first:

```bash
python3 -m py_compile scripts/botctl.py scripts/verify_foundry.py
python3 scripts/botctl.py --help
```

A useful offline instance has parseable Python and all five subcommands in help. Check `pi --version` only before an explicitly requested live drive.

## Drive

Use `scripts/botctl.py`. Its public surface is:

```bash
python3 scripts/botctl.py create --spec examples/evidence-scout.json --output <scratch> --dry-run --json
python3 scripts/botctl.py create --spec examples/evidence-scout.json --output <scratch> --json
python3 scripts/botctl.py validate <scratch>/evidence-scout --json
python3 scripts/botctl.py inspect <scratch>/evidence-scout --json
umask 077
TASK_FILE="$(mktemp "${TMPDIR:-/tmp}/pi-bot-task.XXXXXX")"
${EDITOR:-vi} "$TASK_FILE"
python3 scripts/botctl.py run <scratch>/evidence-scout --task-file "$TASK_FILE" --json
rm -f -- "$TASK_FILE"
python3 scripts/botctl.py smoke <scratch>/evidence-scout --json
```

Fill, save, and close the editor before the run. Never interpolate task text into a shell command. The final command removes only the private `TASK_FILE` created and owned by this caller.

Read [references/features/README.md](references/features/README.md) and the matching feature file before a focused drive.

## Evidence

`verify_foundry.py` writes no report by default. Use `--report <private-path>` only when a private audit artifact is actually needed; reports can contain local paths and runtime output and must never be committed. A profile smoke returns JSON with timestamp, command, Pi version, exit code, stdout, and stderr. It launches with parent context files disabled, drives the real `/start` prompt, and requires the workflow Skill's unique marker plus the exact one job and every anti-job from `BOT.json`; process exit alone is insufficient. Settings/tool consistency remains a static validator check.

## Cleanup

`verify_foundry.py` owns a unique system temporary directory and removes it after the run. Manual drives must also use a new temporary path. Never point a test at `bots/` unless the resulting Bot is an intentional deliverable.

## Helpers

- `scripts/botctl.py` is the product CLI.
- `scripts/verify_foundry.py` is the rerunnable end-to-end verifier.
- `tests/test_botctl.py` covers contract parsing, atomic creation, dry-run, overwrite refusal, tool boundaries, generated settings, and adversarial argv-safe task execution.
- `tests/test_public_release.py` checks portability and the public manifest.