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.*