Q-12: External Agent Coordination

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

Prior Answers Checked

• Q-00 Architecture Synthesis: confirms external agents are part of the architecture, LLM-wiki as shared depot, T0-T7 lifecycle
• Q-01 Pi Teams Fit: notes pi-teams has no concept of "agents outside this team"; external coordination is a custom layer on top via EXTERNAL-AGENT-PROMPT.md + claim-board.md
• Q-04 Work Shape / Lifecycle: identifies external agent coordination as an area needing clarification, with explicit boundaries needed
• Existing EXTERNAL-AGENT-PROMPT.md: the current working protocol being evaluated
• Existing claim-board.md and log.md: demonstrate the CLAIM/RELEASE pattern in practice

What prior answers already establish: - External agents MUST write to LLM-wiki, not Pearl Brain (Q-00, EXTERNAL-AGENT-PROMPT.md rule #8) - External agents pick one OPEN question from research-queue.md (EXTERNAL-AGENT-PROMPT.md) - The claim/check-in/release pattern coordinates via claim-board.md + log.md (Q-01, Q-04) - External agents avoid Pi-specific runtime work (EXTERNAL-AGENT-PROMPT.md, Q-01) - The answer template provides a consistent format (answer-template.md)

Remaining gap before this answer: - No consolidated specification for how external agents should be prompted, onboarded, and coordinated - Collision avoidance rules exist but are scattered across three files - Completion semantics (done/partial/blocked/stale) are implicit, not explicit

Short Answer

The existing EXTERNAL-AGENT-PROMPT.md protocol is effective and should be the canonical external agent prompt with minor hardening. External agents need exactly: (1) the prompt file, (2) the claim board, (3) the answer template, and (4) a hard list of Pi-specific items to ignore. The CLAIM -> CHECK-IN -> RELEASE pattern on the claim board is sufficient for collision avoidance. No additional infrastructure (Forgejo auth, Docker access, Pi agent accounts) is needed. External agents write to LLM-wiki via file writes on the Pi filesystem (or via the coordinating human running on a machine with Tailscale access).

Evidence

1. Current EXTERNAL-AGENT-PROMPT.md Analysis

The existing file at /mnt/kitchen/from-house/workspace/d3-tui-pi-teams-proto/EXTERNAL-AGENT-PROMPT.md already provides:

2. Collision Avoidance - Observed Patterns

Examining the claim board and log shows 4 external agent claims to date:

Collision was successfully avoided in all cases - no two agents claimed the same question simultaneously. The current CLAIM -> check claim-board -> pick another pattern works when agents follow it.

3. Pi-Specific Boundaries - What External Agents Should Ignore

Current EXTERNAL-AGENT-PROMPT.md lists 10 items. Observed risks from the log:

Additional needed boundary: Direct editing of pi-teams config files (config.json, teams.yaml) - external agents should recommend config changes in answers, not apply them.

4. Answer Format - What Makes Answers Buildable

Analysis of existing answers (Q-01, Q-02, Q-04, Q-05, Q-06) reveals:

Strengths of current format: - Consistent template (answer-template.md) - "Prior Answers Checked" section creates dependency chain - "Decision Needed From Mehdi" isolates human decisions - "Next Probe" enables follow-up - Relative links to other answers

Gaps: - No explicit "Contradictions" section - Q-04 and Q-00 express slightly different views on external agent coordination but don't cross-link - No "Depends On" metadata - answer headers don't list which prior answers they depend on - Inconsistent use of links between answers (Q-01 links Q-05 and Q-06; Q-02 doesn't link any)

5. Completion Semantics

The protocol uses four release statuses but their boundaries are implicit:

Stale: Not a release status but a claim state. A claim older than 90 minutes with no check-in is stale. Observed: Q-09 claim from 00:05Z was stale by 01:35Z. The protocol allows later agents to take over stale claims - this worked correctly.

Fit For This Pi Workcell

Exact External Agent Prompt

The current EXTERNAL-AGENT-PROMPT.md is the canonical prompt. Recommended hardened version (changes marked with [HARDENED]):

# External Agent Prompt

You are joining the D3-TUI Pi Teams prototype workcell as an individual operator.

Workcell path on relik-pi4:

`/mnt/kitchen/from-house/workspace/d3-tui-pi-teams-proto`

D3-TUI repo path:

`/mnt/kitchen/from-house/repos/d3-tui`

Knowledge depot:

`/mnt/kitchen/from-house/workspace/d3-tui-pi-teams-proto/llm-wiki`

Read first (in this exact order):

1. `llm-wiki/AGENTS.md`
2. `llm-wiki/SCHEMA.md`
3. `llm-wiki/wiki/research/README.md`
4. `llm-wiki/wiki/research/research-queue.md`
5. `llm-wiki/wiki/tasks/claim-board.md`
6. `llm-wiki/wiki/research/answer-template.md`
7. `llm-wiki/wiki/tasks/task-lifecycle.md`

[HARDENED] After reading, verify: check `llm-wiki/log.md` for any claims newer than the claim board.

Your job:

Answer exactly one unchecked (OPEN) architecture/recovery research question from `llm-wiki/wiki/research/research-queue.md`, unless the user explicitly assigns a different item.

The current priority is not D3-TUI implementation. The priority is to answer the open planning questions about the Pi agent setup and its alternatives: pi-teams, LangGraph, CrewAI, AutoGen/Microsoft Agent Framework, PydanticAI, LlamaIndex/RAG, Docker, pi-container-sandbox, Forgejo workflow, KOS/toolchain, Bun/Pi install shape, validation/smoke testing, and remote UI access.

You are an individual operator, not a Pi team member. Do not worry about Pi-specific mechanics unless the assigned chunk explicitly says so. In particular, do not try to manage:

- Pi installation (apt, bun, npm, system packages)
- pi-teams panes (tmux layout, agent lifecycle)
- tmux sessions (attach, detach, resize)
- Docker image/service setup (build, run, compose)
- pi-teams config files (config.json, teams.yaml)
- Model keys (API keys, provider credentials)
- Provider configuration (model routing, fallback)
- KOS/Flycast runtime wiring (toolchain, compilation, emulator)
- Forgejo authentication or credentials
- Pearl Brain writes

[HARDENED] Your ONLY interface to the workcell is reading and writing files under `/mnt/kitchen/from-house/workspace/d3-tui-pi-teams-proto/llm-wiki/`. Write answers; do not apply config changes.

Protocol:

1. Verify `llm-wiki/wiki/research/research-queue.md`, `llm-wiki/wiki/tasks/claim-board.md`, and `llm-wiki/log.md` [HARDENED: check log.md for claims not yet on the claim board].
2. If an item has an active claim less than 90 minutes old with a check-in in the last 90 minutes, choose another item unless explicitly assigned.
3. [HARDENED] If an item has a stale claim (>90 minutes with no check-in), the item is free. Cite the stale claim in your new claim.
4. Write a claim to both claim-board.md and log.md before you research.
5. Before answering, read any existing answer paths linked from the question and write what prior answers already establish.
6. Write the answer into the question's specified `Answer path` using `answer-template.md`.
7. Mark the question status in `research-queue.md` as ANSWERED, PARTIAL, or BLOCKED, and link your answer.
8. If you are implementing, only work after T0-T3 are written for the task. Default to research only.
9. Do not use Pearl Brain from inside this workcell.
10. Do not modify unrelated FROM/Shachi/Hermes paths.
11. Do not patch KOS/toolchain in place unless explicitly assigned a toolchain-lane task.
12. [HARDENED] Use Forgejo as durable repo ledger only when Forgejo credentials are explicitly provided by the coordinating human. Otherwise use the wiki claim board and log.md as the durable ledger.
13. Do not coordinate panes or Pi agents; leave Pi-specific orchestration to the Pi team lead.
14. [HARDENED] Release the claim with HANDLED, PARTIAL, BLOCKED, or RELEASED status. Write the release to both claim-board.md and log.md.

Claim template:

    ### CLAIM: <task-id> | <agent/session> | <timestamp UTC>

    Status: CLAIMED
    Lease: 90 minutes unless refreshed
    Task: <issue/chunk/path>
    Stage: T0/T1/T2/T3/T4/T5/T6/T7
    Scope: <what this session will answer/do>
    Expected output: <wiki path / Forgejo comment / patch>

Answer/release template:

    ### RELEASE: <task-id> | <agent/session> | <timestamp UTC>

    Status: HANDLED / PARTIAL / BLOCKED / RELEASED
    Output: <links>
    Summary: <brief>
    Next: <follow-up>

Before final response, report:

- claim written
- files changed
- output/depot path
- remaining blockers

Changes from current EXTERNAL-AGENT-PROMPT.md: 1. Added explicit verification step (check log.md for newer claims) 2. Added stale claim takeover rule (cite the stale claim) 3. Hardened Pi-specific boundaries list (added config files) 4. Clarified Forgejo access (only when human provides credentials) 5. Required release to be written to both claim-board AND log 6. Added interface boundary statement ("write answers; do not apply config changes")

Collision Avoidance Protocol

The current three-source check (research-queue.md -> claim-board.md -> log.md) is correct. The key insight: log.md is the strongest consistency check because it has timestamps for every action, including claims that someone forgot to add to the claim board.

Recommended collision check sequence:

1. Read research-queue.md -> identify OPEN questions
2. Read claim-board.md -> filter out CLAIMED questions
3. Read log.md -> filter out questions with claims in log but missing from claim board
4. For each remaining candidate: verify the claim is NOT <90 minutes old
5. If all OPEN questions are claimed: report to user, do not double-claim

Edge case - log/claim-board mismatch: If log.md shows a CLAIM for Q-NN but claim-board.md does not, and the claim is <90 minutes old: treat as CLAIMED. Write a note to log.md: "Q-NN appears claimed in log.md at but missing from claim-board.md. Treating as CLAIMED."

What Counts as Done / Partial / Blocked / Stale

Stale claim detection: 1. If claim is >90 minutes old AND has no CHECK-IN in the last 90 minutes -> STALE 2. If claim is >90 minutes old but has a recent CHECK-IN -> NOT stale (lease refreshed) 3. Stale claims can be taken over by citing the stale claim in the new claim: TAKEOVER: Q-NN was claimed by <agent> at <timestamp>, stale as of <now>. Taking over.

Onboarding Sequence

The exact order matters - later files reference earlier ones:

1. AGENTS.md          -> "This is the knowledge depot. Write here, not Pearl Brain."
2. SCHEMA.md          -> "These are the conventions for page types and log format."
3. research/README.md  -> "You're here for architecture research, not implementation."
4. research-queue.md   -> "Here are the OPEN questions. Pick ONE."
5. claim-board.md      -> "Here's who's working on what. Don't double-claim."
6. answer-template.md  -> "Here's the format for your answer."
7. task-lifecycle.md   -> "Here's the T0-T7 stages if your question spans stages."

Note: log.md is not in the initial reads but should be checked immediately after for claim verification. The hardened prompt adds this as step "After reading, verify."

How External Agents Should Write Answers

1. Use the template: answer-template.md is the standard. Do not deviate.
2. Link prior answers: Use relative links [Q-01](/wiki/research/answers/q-01-pi-teams-fit.html).
3. Contradictions section: If you find a contradiction with a prior answer, add ## Contradictions Found section linking both answers.
4. Keep Pi-specific speculation out: If a nested question asks about Pi mechanics, answer it in principle using known constraints (RPi4 4GB, ARM64, Docker), not by attempting Pi commands.
5. Be specific in recommendations: "Use X" not "Consider X." The lead (Q-00) synthesizes. External agents provide definitive answers.
6. Short answer first: The first section after Prior Answers is "Short Answer" - one paragraph with the direct recommendation. Pi agents reading this for synthesis should not need to read the full document.

Self-Referential Observation

This Q-12 answer itself was written by an external agent (opencode) following the protocol. This serves as a live validation:

• Claim: Written to claim-board.md and log.md at 03:05Z
• Collision check: Verified Q-03 and Q-11 were actively claimed; Q-07, Q-08, Q-09, Q-10, Q-12 were OPEN
• Prior answers read: Q-00, Q-01, Q-04, plus EXTERNAL-AGENT-PROMPT.md, claim-board.md, log.md
• Answer format: This document uses answer-template.md
• Pi boundaries respected: No Docker commands, no config edits, no Pi agent coordination attempted
• Pearl Brain not queried: Respected rule #8
• Files written via SSH: Used heredocs - the simplest possible write mechanism

Risks / Failure Modes

1. Claim-Board / Log Drift: If an agent writes a claim to one but not the other, the next agent may only see half the picture. The hardened prompt requires writing claims AND releases to both.

2. External Agent Access Method Unknown: The prompt assumes the agent can read/write files on the Pi. If the coordinating human copies files manually instead of giving SSH access, the agent cannot verify claims independently. Mitigation: The human should be instructed to copy the current research-queue.md and claim-board.md alongside the prompt.

3. Stale Claims Accumulate: Without cleanup, the claim board will grow unbounded. A Pi agent (lead) should periodically sweep and archive stale claims. Not an external agent responsibility, but worth noting.

4. Contradicting Answers: If two external agents answer related questions independently, they may contradict each other. The lead (Q-00 synthesis) is the arbiter, but there's no mechanical contradiction detection. Mitigation: The "Prior Answers Checked" section, if done thoroughly, catches most contradictions.

5. External Agent Doesn't Understand Pi Constraints: An agent without Pi 4 awareness may recommend solutions that work on x86 but not ARM64/Docker. Mitigation: The prompt should include a one-line hardware constraint: "Target: Raspberry Pi 4, 4GB RAM, ARM64, Docker on Debian."

6. Prompt Drift: If EXTERNAL-AGENT-PROMPT.md is updated, agents reading an old copy get stale instructions. Mitigation: The prompt should include a version and "check for updates" step.

Decision Needed From Mehdi

1. Hardened prompt adoption: Should the hardened EXTERNAL-AGENT-PROMPT.md in this answer replace the current one? (Recommended: yes - 6 non-breaking improvements, no new infrastructure.)
2. Hardware constraint line: Add "Target: Raspberry Pi 4, 4GB RAM, ARM64, Docker on Debian" to the prompt? (Recommended: yes.)
3. Log sweep: Should a Pi agent (lead) periodically archive stale claims from the claim board? (Recommended: yes, weekly sweep.)
4. Prompt versioning: Add version number and "check for updates" step to EXTERNAL-AGENT-PROMPT.md? (Recommended: yes, v1.0 with last-updated timestamp.)

Next Probe

The smallest follow-up check: send the hardened EXTERNAL-AGENT-PROMPT.md to a fresh external agent (different model or session) and observe whether they: 1. Check all three sources (queue, board, log) before claiming 2. Pick an OPEN question without colliding 3. Produce a properly formatted answer following the template 4. Release the claim to both board and log

This validates the protocol end-to-end before the lead synthesizes all answers into Q-00.