mcpctl/docs/session-summary-vision-fidelity.md

Session Summary — Vision Fidelity in Agentic Teams (full discussion)

Status: Consolidated session record — captures everything discussed, in order, so it reads as one coherent thread. Date: 2026-08-08 · pi session · mcpctl repo

IMPORTANT — canonical doc: since this summary was written, agentic-teams.md was updated and is now the single authoritative, unified design document that supersedes this summary plus vision-fidelity.md, epic-task-artifact-model.md and agentic-teams-review.md. Read agentic-teams.md for the source of truth; this summary is the session narrative and highlights the sections the canonical doc added beyond it.

---

Part 1 — The problem statement

We started with a recurring failure with LLM coding agents:

1. you had a grand vision
2. we split the grand vision into tasks
3. we completed all the tasks
4. we are left with a stick with wheels instead of a car

Every task completed, yet no car. The diagnosis (see vision-fidelity.md for the full write-up): this is not an execution problem — it's decomposition + verification.

Root causes

1. Decomposition is lossy — a multidimensional vision compresses into flat imperatives; the why and what-good-looks-like get dropped.
2. Tasks are graded mechanically — "compiles / lint / renders," never "does this serve the vision / is this designed / does this feel finished."
3. Integration is nobody's job — a car is parts working together, but task systems execute a list.
4. No feedback loop — the agent assumes task 3 was fine and never re-checks against the original vision.
5. Design/product review is a phase, not a gate — applied at the end, when the wrong shape is already baked.

Research synthesis (from the write-up)

• Vertical slices / walking skeleton — decompose into mini-wholes (user-visible, end-to-end slices), not layers. Always have a small car, not a pile of parts.
• Two-tier Definition of Done — mechanical tier + systematic tier (matches vision, integrates, is designed, feels finished). Tier-2 evaluated by running the medium, not reading code.
• Review-gate HITL over per-tool approval — consistent with round-2.
• Spec-driven + media-native verification — judge an artifact in its native medium (render/run for UI).
• Critic-agent pattern — a non-executing persona that reviews against the vision catches drift the working agent's confirmation bias misses.

---

Part 2 — Grounding in the repo (the "other window")

We confirmed this connects to real, existing machinery:

• mcpctl agent platform — persistent agent personas, project prompts, ResourceRevision (versioned log), ResourceProposal (review/approve queue), personalities (same agent, different judgment via prompt overlays).
• gstack skills (installed skill library) — /autoplan (auto-review pipeline: CEO → Design → Eng → DX), /plan-ceo-review (grand-vision guardian, nuclear scope challenge, 10x vision), /plan-design-review (rates each design dimension 0-10, generates visual mockups, "text descriptions are not a substitute for showing what it looks like"), /spec.
• agentic-teams.md + agentic-teams-review.md — the durable design record, landed on async, artifact-driven, human-as-fuse (section 1 of the review round is the through-line).

Key realization: the platform reviews the plan hard before build, but nothing reviews the built result against the vision after implementation, and no vision artifact exists as a first-class, versioned resource. That's the gap today's design fills.

---

Part 3 — Where we landed: the Epic model

We reframed VISION.md → Epic, in Jira nomenclature — and it's the thing we discussed in this window's second half. Full spec in epic-task-artifact-model.md.

The Epic is the vision

• The back-and-forth discussion before coding starts is the vision; the Epic captures its conclusion. It's project-scoped.
• Holds the agreed "done" criteria (checkable outcomes + intent/quality attributes) written at vision time, plus scope-change history (revisions) and accepted-tradeoff decisions.

Epic lifecycle — "done" only two ways

An Epic reaches done only when:

1. 100% of the vision is delivered, OR
2. The user explicitly accepted tradeoffs (e.g. an issue we couldn't fix) — recorded on the Epic, so done is honest + auditable.

The comparison moment is the exec trigger. Delivered-whole vs Epic → gaps route to:

• reopen under-delivering tasks, or
• new tasks for never-decomposed pieces, or — when it's a hard "we couldn't fix X" — a joint exec debugging session (the pi / Claude-Code live experience). This gives exec a concrete, principled trigger.

---

Part 4 — Data model: task / epictask / Epic

Hierarchy (details in epic-task-artifact-model.md §2):

Epic (the vision)
  └── epictask — roadmap node; tasks hang off it; chains to other epictasks
        └── task — the unit of work (own lifecycle from round 1)

• tasks link to epictasks; epictasks chain to each other → visualizing all epictasks gives a spider-web roadmap (dependency graph, not flat).
• Walking any task up the chain reaches the Epic's "done" criteria, so tier-2 / vision DoD is reachable from every task.

Reopen vs new-task

Gap cause	Outcome
A task under-delivered its acceptance criteria	Reopen (directional comment back)
A piece was never decomposed (breakdown gap)	New task under the epictask
Hard problem / needs joint effort	exec joint session

---

Part 5 — Artifacts + IPython-style context (prime-agent philosophy)

Borrowed from prime-agent's "context as variables / prompt-as-a-variable" (details in §4 of the model doc):

• Artifacts are objects, not plain text — files|test, logs, and also PR & commits as structured objects with an expand operation (not dumped into context).
• "Cat" → variable/artifact — a named, retrievable reference, not auto-injected.
• Rule: context does NOT auto-populate from artifact content.

Eviction / flush priority (recoverability-driven)

1. User's words — highest retention.
2. Agent's words — next.
3. Artifact context — evict first, because artifacts are durably stored and recoverable via expand. Eviction priority follows recoverability.

The elegant win: dropping artifact-context first is cheap because it's recoverable — most compaction schemes don't formalize this, and it turns a hand-wavy "compaction" into a principled hierarchy.

---

Part 6 — Open questions / tensions (carried forward)

1. Epic as a resource vs a prompt — own resource type (RBAC + revisions) or reuse project prompt/skill? Lean: own resource.
2. Epic-level vs epictask-level "done" — should epictasks carry their own acceptance criteria so the spider web shows per-node completeness? Lean: yes.
3. Comparison unit: task-level or epictask-chain-level? A gap can cross multiple linked epictasks; a single "reopen" may not express "this chain is incomplete." Decide whether comparison happens per-task or per-chain.
4. exec as a deliberate carve-out — the async model is default, but the Epic-gap triggers sync exec by design. Name this so it doesn't conflict with the round-2 async decision (LE-4).
5. Accept-tradeoffs needs structure — record what, why, who, de-scoped-by as a revision on the Epic.
6. Naming (LE-7) — epictask spelling; and task vs repo's .taskmaster tasks.
7. Artifact storage — server-side mcpctl-owned for binaries/builds (per LE-8/LE-5); commits/PRs stay in git/repo and are referenced as objects.
8. Post-build re-verification — the remaining product-side gap: nothing re-checks the rendered/built result against the reviewed mockup/vision after implementation (the design-review/qa path is opt-in, not wired into the Epic-comparison loop).

---

Referenced artifacts produced today

File	Purpose

See docs/agentic-teams.md — now the single unified document (supersedes vision-fidelity.md, epic-task-artifact-model.md, agentic-teams-review.md, and this summary).

Part 7 — What the canonical agentic-teams.md added beyond today's thread

When reviewing the updated docs/agentic-teams.md (which folds in everything we discussed), these sections were found to be new / more evolved than the session thread above — worth reading there:

1. Two-level verification model (§3) — formalised table: Tier 1 Correctness/Security/Ops (inside the task lifecycle) vs Tier 2 Vision Fidelity/Design (at the Epic, media-native). They do not replace each other.
2. SRE/Release review stage (§6) — Tier-1 stage inside the task loop that reviews deployment-as-code (IaC, release manifests, container config) against the project's actual deployment model/infra (Kubernetes vs Portainer vs EC2 vs local). Worked example: a missing network egress policy silently blocks traffic and a developer LLM deep-dives the wrong debugging path — so the SRE persona must carry per-project infra gotchas.
3. Task lifecycle expanded (§6) — InProgress → Build/Run → Self-Testing → QA → Security → SRE/Release → Done → AwaitingReview → accept→Merged / reject→InProgress, with stage feedback bouncing back to InProgress.
4. Script artifacts (§11) — a script artifact kind (tool-as-a-script, like a skill but as code) at three scopes: task / project / agent. Captures a procedure once instead of re-deriving it; context-saving via expand; learned-and-reused.
5. Baseline scorecard / "basics rules agent" (§11b) — a provisioned default list of baseline rules (e.g. "always make unit tests") checked by a scorecard agent; distinct from Tier-1 QA/Security/SRE and Tier-2 critic — a baseline-behaviour/standards gate.
6. Artifact term collision (§11) — the noun collision resolved: build-artifact store (durable storage for binaries) vs context-artifact (lazily-loaded, expandable object in the LLM window). Two axes, one noun; must not be conflated.
7. Hotfix motivating example (§4) — delta-check vs full-rescan economic argument for memory + coverage ledger.
8. Collaboration modes (§5) — standup (on-demand, artifact-driven), joint debugging/architecting, present architectural decisions, ask-the-human-for-help, work-alone-when-confident.
9. Consolidated open questions (§15) — now 16 items, including brain ownership, naming (LE-7), prompt delivery, exec carve-out, Epic vs epictask done, Epic-as-resource, comparison unit, accept-tradeoffs structure, artifact storage, merge recovery, dashboard surface, Tier-2 media-native infra, MVP order, script-artifact design, incentive & scorecard.
10. MVP path (§16) — 8 steps now include the vision layer (Epic/epictask/task) first, then runtime adapter, lifecycle + QA/Security/SRE, Tier-2 critic + Epic-comparison, collaboration modes, confidence/dashboard, memory/coverage + context-artifacts, then script artifacts + baseline scorecard.