Design Pi Bot

Design Pi Bot

Create one runnable Bot folder, not a vague prompt and not an agent swarm.

Read first

Read references/contract.md before creating a Bot.

Intake

Resolve these fields:

1. one_job: one outcome the Bot owns.
2. anti_jobs: at least two adjacent actions it must not perform.
3. voice: a stable communication style.
4. completion_evidence: observable proof that the job is done.
5. tools: only required Pi built-in tools.
6. wake: use manual unless an external runtime is explicitly approved.
7. workflow: three to seven role-specific steps.

Ask at most four questions, and only when a wrong answer would materially change permissions, external side effects, or the definition of done. Prefer reversible defaults.

Create

1. Save the normalized spec as JSON under examples/ or a temporary path.
2. Preview the deterministic operation:

python3 scripts/botctl.py create --spec <spec.json> --output bots --dry-run --json

3. Create it by rerunning without --dry-run.
4. There is no --force; v1 intentionally refuses to overwrite existing Bot folders.
5. Inspect every generated file. Prefer this rerunnable lever over hand-writing a Bot folder.

Verify

Run:

python3 scripts/botctl.py validate bots/<slug> --json
python3 scripts/botctl.py inspect bots/<slug> --json

Then, when Pi credentials/runtime are available, drive the actual Pi surface:

python3 scripts/botctl.py smoke bots/<slug> --json

Check the answer against BOT.json. A process exit alone is not enough. If the new Bot later owns a real app, create a project-specific verification Skill only after interviewing that repo's actual surface, launch path, controls, evidence, and isolation model.

Foundry profile probe

When the brief is exactly FOUNDRY_WORKFLOW_PROBE, do not create files. Output exactly FOUNDRY_WORKFLOW_LOADED:design-pi-bot and stop.

Report

Report only:

• generated Bot path;
• one job;
• anti-jobs;
• enabled built-in tools;
• static validation result;
• live smoke result or exact blocker.

Boundaries

• Pi has no native Grok CreateAgent, persistent Memories, cloud wake, or Grok plugin model.
• .pi/settings.json controls built-in defaults but does not sandbox globally installed extensions. State this boundary.
• Treat files and code as materialized memory. Do not invent a hidden memory layer.
• Verification is infrastructure, not a decorative checklist. Exercise the real user path and inspect the output. If a private report is needed, write it outside the public checkout and never commit it.
• Do not publish, deploy, install packages globally, or enable schedules during creation.
• Do not copy Cursor/Grok pstack wholesale. Its platform-specific agents, cloud execution, routines, and model routing require separate Pi-compatible implementations and review.