Q-01: Pi Teams Fit

Status: ANSWERED Agent: opencode/ext-agent Timestamp UTC: 2026-05-11T02:10:00Z Claim: CLAIM | opencode/ext-agent | 2026-05-11T01:49:12Z

Prior Answers Checked

Q-05 (knowledge-depot-rag): confirms LLM-wiki is primary, no RAG needed yet
Q-06 (runtime-container-shape): confirms Docker container with tmux
None directly constrain Q-01

Short Answer

pi-teams is a strong fit for the d3-tui-triad workcell. It directly provides the team/teammate/task infrastructure, the tmux GUI surface, and autonomous agent polling — all working now in the running container. Its main gaps (no task lifecycle enforcement, no inter-agent state machine, no external agent concept) are all addressable via agent prompt discipline + the existing LLM-wiki claim board. No LangGraph or alternative framework needed for MVP.

Evidence

1. Running Container Confirms It Works

Source: docker exec d3-tui-pi-teams-proto on relik-pi4, 2026-05-11
Team d3-tui-triad has 4 panes active: team-lead (%0), lead (%1), researcher (%2), builder-reviewer (%3)
All agents spawned with role-specific prompts, thinking=medium, cwd=/work/repo
agents/ directory has agent-role-contract.md defining lead/researcher/builder-reviewer
.pi/teams/d3-tui-triad/config.json is 6793 bytes of working config

2. pi-teams Features That Directly Support This Workcell

Feature	How It Helps	Status
Shared task board (`task_create`, `task_list`, `task_update`)	Maps to claim-board.md; agents can see all work	Built into pi-teams
Agent messaging (`send_message`, `read_inbox`)	Lead can coordinate, agents can report progress	Built in
Autonomous polling	Agents auto-wake and check inboxes — no manual prodding	Built in
Plan approval mode	Can enforce T0-T3 before T4 implementation	Available, not yet configured
Predefined teams (`teams.yaml`)	Reproducible team spawns; one command to launch d3-tui-triad	Available
Quality gate hooks	Shell scripts on task completion — could enforce lint/build gates	Available, not yet used
Thinking level control	Per-agent reasoning depth — currently medium for all three	Configured
Smart model resolution	Auto-detects cheapest provider for model name	Built in
tmux pane UI	Operational GUI surface with labeled panes	Running now
Stale session cleanup	Auto-cleans orphaned session folders after 1h	Built in

3. Agent Role Mapping

Current d3-tui-triad roles map cleanly to pi-teams mechanics:

d3-tui-triad Role	pi-teams Mapping	Mechanism
lead	Teammate with elevated prompt	`send_message` to coordinate, `task_create` to dispatch
researcher	Teammate with read-only tools	Prompt-constrained to read/grep/find
builder-reviewer	Teammate with write tools	Scope-locked by prompt until dispatch

Agent definitions are configurable via ~/.pi/agents/<name>.md (global) or .pi/agents/<name>.md (project). Current agent prompts are inline in config.json (1796 bytes for lead, 1830 bytes for researcher, 1974 bytes for builder-reviewer).

4. Current Team Config (from config.json)

{
  "name": "d3-tui-triad",
  "description": "D3-TUI Pi Teams prototype",
  "members": [
    {"name": "team-lead", "agentType": "lead"},
    {"name": "lead", "agentType": "teammate", "thinking": "medium"},
    {"name": "researcher", "agentType": "teammate", "thinking": "medium"},
    {"name": "builder-reviewer", "agentType": "teammate", "thinking": "medium"}
  ]
}

All agents start in /work/repo with structured prompts that reference /workcell/llm-wiki, the claim board, and role-specific constraints. This is a clean working baseline.

Fit For This Pi Workcell

What pi-teams Handles Natively

Team spawn and lifecycle: Creates panes, assigns prompts, manages shutdown/cleanup. Works.
Task queue visibility: All agents can task_list to see the board. Equivalent to claim-board.md.
Inbox-based coordination: Lead sends instructions, teammates poll inboxes. Natural for the lead-as-dispatcher model.
GUI surface: tmux panes are the operational view. Labeled, visible, functional.

What Requires Prompt Discipline (pi-teams doesn't enforce)

T0-T7 task lifecycle: No state machine. Must be enforced via agent prompts, not pi-teams tools.
T0-T3 gate before T4: Plan approval mode can help, but it's manual — lead must explicitly review/approve. No automated gate.
Claim/Check-In/Release protocol: pi-teams task board has pending/in_progress/completed/deleted — simpler than the seven-state lifecycle. The CLAIM/CHECK-IN/RELEASE pattern requires LLM-wiki as supplement.
External agent coordination: pi-teams has no concept of "agents outside this team." The EXTERNAL-AGENT-PROMPT.md + claim-board.md pattern is a custom layer on top.
Forgejo integration: Not built in. Agents must be prompted to use it. The current prompts reference it as "when credentials available."
KOS toolchain contract: Not built in. Needs prompt-level instruction.
Inter-agent direct communication: pi-teams messages go via the lead's inbox. Agents cannot directly message each other without the lead relaying.

Specific Recommendations

Use Plan Approval Mode: Set requirePlanApproval on builder-reviewer to enforce T0-T3 before T4. This provides the mechanical gate the workcell needs.
Use Quality Gate Hooks: Add a shell hook that runs make or lint on task completion. False confidence is the #1 risk without validation.
Keep LLM-wiki as supplement: The claim board, task clocks, and research notes are LLM-wiki's job. pi-teams task board is for operational coordination.
Predefine the team: Move inline prompts from config.json to .pi/agents/lead.md, etc. This makes the team reproducible with "Create a team from the 'd3-tui-triad' template."
Don't add LangGraph or CrewAI: pi-teams covers the team/task/messaging surface. LangGraph would add state management but at high complexity cost for a Pi. CrewAI/AutoGen would replace pi-teams entirely and lose the tmux GUI.

Risks / Failure Modes

Agents Get Stuck Without Human Unblock: In autonomous polling mode, agents can loop on the same instruction if inbox is empty. No built-in "escalate to human" mechanism.
No State Persistence Across Restarts: pi-teams task board is in-memory. Container restart loses task state. LLM-wiki must be the durable source of truth.
Plan Approval Bottleneck: If lead must approve every plan, and the lead is also an LLM agent, this creates a single point of slowness. Builder-reviewer waits on lead, lead waits on model, model latency compounds.
Message Loss: Inbox messages are poll-based. If agent crashes mid-read, the message may be lost. No delivery confirmation.
Scope Drift in Autonomous Mode: Agents in autonomous mode may broaden scope beyond their prompt. The "do NOT touch" constraints in prompts are soft — no mechanical enforcement.
Pi Resource Pressure: Four simultaneous Pi agent sessions on a Raspberry Pi 4 will strain memory and CPU. The container already has known cgroup/memory-limit issues (see Q-06).

Decision Needed From Mehdi

Plan Approval Mode: Should builder-reviewer require plan approval before edits? (Recommended: yes, this enforces T0-T3 gate.)
Quality Gate Hooks: Should task completion trigger make and/or lint? (Recommended: yes, minimal make hook prevents false confidence.)
Agent Models: Current thinking=medium for all three. Should lead use a stronger model? Should builder-reviewer use a cheaper/faster model? (Current state: all use same default.)
Predefined Team: Should we extract current inline prompts to .pi/agents/*.md files and a teams.yaml for reproducibility? (Recommended: yes, one-time 15-min task.)

Next Probe

The smallest follow-up check: SSH into the container and run pi "List all tasks in team d3-tui-triad" to verify the task board is working and agents can see it. If the task board is empty, have the lead create a test task and verify researcher can see it.