mcpctl/docs/agentic-teams-review.md

Agentic Teams — Second Review Round

Status: Second design review round. Complements and refines docs/agentic-teams.md (the primary design record). This file captures the loose ends surfaced by reviewing the first draft, and the decisions/recommen- dations that followed.

Date of round: second pass. Like the base doc, this is feature/decision- focused, not code-focused. Items marked [OPEN] are not yet decided and block or shape implementation. Items under "DECIDED in this round" are resolutions reached here.

---

0. What this round covered

Reviewing the first draft surfaced several loose ends, tensions, and undefined mechanics that would have bitten during implementation. They cluster into one through-line question (below), then several specific items. The single most important framing decision this round is async-vs-sync, because it resolves most of the others.

---

1. THE through-line decision: async vs sync [mostly DECIDED — see below]

Most of the loose ends collapse into one question:

Is the system fundamentally synchronous-team (everyone—agents and human—working "together" in near-real-time, waiting on each other), or asynchronous (frozen artifacts + a decision queue + disposable pods)?

Where this landed (DECIDED in this round):

The system is fundamentally asynchronous and artifact-driven, with exec being the deliberate exception the human opts into for joint active work. Evidence from the whole conversation supports this:

• Confidence checks run on frozen task artifacts, not live chat.
• The human supervises from a single dashboard/inbox of packaged decisions.
• Pods are ephemeral and disposable by design.
• State lives in mcpctl's database (not in pods).
• Agents escalate packaged questions, not live interjections.

Locking this resolves loose ends 1, 2, 3 and 4 (below) together, and makes the design more robust (no idle synchronous chains, no live-session coordination, everything auditable and resumable). exec remains available, but it is a different activity (joint active collaboration) rather than the default way work proceeds.

---

2. Loose ends surfaced & resolution status

🔴 LE-1: Do reviewers (QA/security) block the working agent, or run async?

The tension: if a working agent submits and reviewers run in their own pods, does the working agent block (idle for minutes/hours) or end its session and get resumed only if rejected?

DECIDED (recommendation, consistent with async model): reviewers run asynchronously against the frozen branch/artifact. The working agent's pod can end after submission. A rejection re-spawns a working session with the rejection comment as new input. No idle blocking chains.

This also means we do not need live multi-pod coordination — the handoff is artifacts + verdicts in mcpctl's DB, not a live rendezvous between pods.

🔴 LE-2: Are QA/security verdicts a hard gate, or advisory?

The tension: "QA checks, security looks, CI passes, then submit" implies a gate (all must pass); but the confidence model and "human accept is the only true fuse" imply they're advisory.

DECIDED (recommendation): QA/security review is primarily for the working agent's self-correction (catching issues before it reaches you) and as attached evidence for the human's accept decision. Their verdicts are informative, not hard autonomous gates. The only hard autonomous gate is CI-against-current-main; the human's accept remains the one true fuse.

Reasoning: if reviewer verdicts were hard gates, they'd effectively be an autonomous pre-approval pipeline — the rigid-pipeline shape we explicitly rejected, and the human's accept would become rubber-stamping. Keeping them advisory preserves the human's genuine authority while still giving agents a self-correction loop and giving the human good evidence.

🔴 LE-3: Did we actually decide "standup," and how does it fit the async model?

The tension: "standup" was described early ("standup where we discuss progress since yesterday") but was never designed. It also risks implying a synchronous ritual.

DECIDED (recommendation): a standup is an on-demand, artifact-driven instrospective flow, not a recurring synchronous call. Example shape:

• mcpctl standup --project sre [--since <date|task>] — pull each agent's per-task progress/notes since the last standup and summarize.
• Each agent's requested decisions surface as dashboard items (one queue).
• The human reviews the summary and works the queue asynchronously.

So standup pulls from per-agent per-task notes (where progress actually lives) and feeds the decision dashboard. It does not require anyone to be live simultaneously.

🟡 LE-4: exec vs the async review model — clarify the boundary.

DECIDED (recommendation): exec is for joint active collaboration (debugging / architecting / real-time hands-on), not for inserting into a task already under async review. A task under review is a frozen artifact; exec is the opt-in exception when the human chooses to be live with one agent. This keeps the two modes coherent and avoids expecting to exec into the middle of a review pipeline.

🟡 LE-5: Where does state live given pods are disposable?

DECIDED: State lives in mcpctl's database — task artifacts, verdicts, per-agent notes, coverage ledgers. Pods are stateless workers that read from / write to that state. Nothing is lost on pod death; pods are cheap to re-spawn. This is a strength of the design and worth stating explicitly.

🟡 LE-6: The "brain" question — who powers the agent's LLM? [OPEN → resolve]

The one real open knot from the first round, still not closed.

Recommendation (decided-leaning):

• Bare chat (mcpctl chat agent001): the agent's home brain (agent-owned Llm default).
• --project mode: the project's llmProvider takes over (portability; matches today's project-chat; a project can invite any agent and run it on the project's model of choice).

This blocks the data model, so it should be closed with one decision. It is the single most important unresolved item.

🟢 LE-7 (naming): "Task" may collide with the repo's Task Master workflow.

The mcpctl "Task" resource could conceptually collide with this repo's .taskmaster tasks. Flag for a naming check — e.g., workitem / item / assignment — so the two don't confuse. Not an implementation blocker; flagged because a second pass is the right time to settle naming.

🟢 LE-8 (minor): Where does the artifact store (non-git binaries) live?

Decided earlier that git carries source+verdicts and an immutable artifact store keyed by commit carries binaries/build outputs. Recommendation: that store also lives server-side (mcpctl-owned), keyed by commit/branch, so it survives pod death and pods pull exactly what they need. Consistent with LE-5.

🟢 LE-9 (open): How are project/persona prompts delivered to the pod?

[OPEN] The user explicitly raised this early and we never chose between:

• exposed via MCP (prompts as MCP calls),
• as files placed in the container (prompt files on disk in the pod),
• LLM query injection directly (system-prompt injection at call time).

This affects the pod image and the runtime interface. Lean: a prompt-file-aware coding-agent runtime → files in the container; MCP as an alternative surface; injection-at-call is how today's chat behaves. Should be closed at design time.

🟢 LE-10 (open): The explicit "ask-for-help / joint problem-solving" mode

The user described wanting a mode where they help an agent with a challenge and work on it together — “you can ask me to help you with some challenge and we can work for it together.” This is related to but distinct from exec-into- a-workspace and from hot escalation. It is not fully designed.

Lean: an agent that is stuck or lacks knowledge can request help (an escalation tagged as a help-request), routed to the dashboard or an exec session, rather than the human having to discover it independently.

---

3. Confirmed strengths worth preserving (from round-one, re-affirmed)

While reviewing, we confirmed these hold up and should survive any refinement:

• Agents as persistent "people" (global memory + per-project context + multi-project membership). [DECIDED round one]
• Confidence = evidence-anchored, outcome-aware (attach similar tasks' description + resolution + effect). [DECIDED round one]
• Task-level accept gate (one decisive human accept/reject + comment) rather than per-tool permission — no permission engine rebuild. [DECIDED round one]
• Merge gated on current-main CI + human accept via provider API, with auto-reopen/revert on post-merge failure. [DECIDED round one]
• Coverage-ledger invalidation is the honesty backbone of the memory. [MVP prerequisite]
• Delegation over reinvention — build an AgentRuntime interface; first runtime = battle-tested coding agent headless; pi as a later optional adapter. [DECIDED round one]

---

4. Post-merge concern — revisited and reinforced

The "stuff only fails after merge to master" worry got a concrete resolution in round one, and the async framing reinforces it:

• Pre-merge acceptance must verify against current main tip, not the stale base.
• The human's accept is conditioned on that current-main verification; if main moved and it's stale, stay AwaitingReview flagged rebase-needed (agent refreshes + re-verifies).
• Post-merge, Merged → Reopened on a failure webhook, with fast revert of the task-sized merge as the cheapest recovery.

The async model strengthens this: because each step is a frozen artifact + state transition, a post-merge failure is a routable state (auto-reopen), not a surprise to be debugged live.

---

5. Remaining open questions (consolidated)

To make the design "ready to design," close these:

1. [LE-6] Brain ownership — closed-leaning but not confirmed: home brain for bare chat; project's llmProvider in --project mode.
2. [LE-7] Naming — is the work entity called a "Task" or something else?
3. [MVP-scope] Which vertical slice first — the base doc proposes Task+Repo entities → runtime adapter → accept gate → collaboration modes → confidence/dashboard → memory/ledger. Confirm or adjust the order.
4. [LE-9] Prompt delivery — MCP vs files-in-container vs LLM injection (see LE-9).
5. [LE-10] Ask-for-help / joint problem-solving mode (see LE-10).

---

6. Suggested MVP path (unchanged from base doc, re-listed for completeness)

1. Task + Repo entities + project linkage.
2. AgentRuntime adapter interface + first runtime (existing coding agent headless) inside a pod. Prove: pod spawn → clone → work task branch → push → report.
3. Task lifecycle + PR linkage + human accept gate → merge via provider API (current-main CI + Reopened-on-failure).
4. Collaboration modes: on-demand async standup + exec joint mode.
5. Confidence-driven autonomy + escalation dashboard.
6. Memory + coverage ledger (invalidation-aware).

---

This file records the second review round and its outcome. It should be read together with docs/agentic-teams.md; together they form the durable design record. The async-vs-sync through-line (section 1) is the key decision to carry forward.