| name | design-pi-bot |
| description | Designs and creates one focused local Pi Bot folder from a user brief. Use when the user asks to make, clone, scaffold, or improve a Pi Bot or convert a Grok Bot into a local Pi Agent role package. |
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:
one_job: one outcome the Bot owns.anti_jobs: at least two adjacent actions it must not perform.voice: a stable communication style.completion_evidence: observable proof that the job is done.tools: only required Pi built-in tools.wake: use manual unless an external runtime is explicitly approved.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
- Save the normalized spec as JSON under
examples/ or a temporary path.
- Preview the deterministic operation:
python3 scripts/botctl.py create --spec <spec.json> --output bots --dry-run --json
- Create it by rerunning without
--dry-run.
- There is no
--force; v1 intentionally refuses to overwrite existing Bot folders.
- 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.
