mcpctl/docs/epic-task-artifact-model.md

Epic / Task / EpicTask + Artifact Context Model

Status: Design discussion — capturing decisions from the conversation. Purpose: Durably record the data model (Epic, epictask, task) and the IPython-style artifact/context philosophy the user is designing. Builds on docs/agentic-teams.md (round 1) + docs/agentic-teams-review.md (round 2).

The through-line from round 2 — async, artifact-driven, human-as-fuse — is preserved here. This doc adds the vision layer (the Epic) and the context-management layer (artifacts + eviction priorities) that the earlier rounds never defined.

---

1. The Epic — the vision, made a first-class thing

An Epic is the agreed statement of what we want to achieve. It is the result of the back-and-forth before coding starts: the discussion is the vision, and the Epic captures its conclusion. It is project-scoped.

What an Epic holds

• The agreed "done" criteria — the checkable outcomes plus the intent/quality attributes that define 100% delivery. Written at vision time so "compare delivered vs vision" has something authoritative to diff against.
• Its scope changes over time (revisions), so creep/drift is visible too — not just under-delivery.
• Tradeoff decisions the user makes along the way.

When is an Epic "done"?

An Epic is done ONLY when one of two things is true:

1. 100% of the vision is delivered, OR
2. The user explicitly accepted tradeoffs — e.g. a known issue we couldn't fix ("we accept this gap because"). The accepted-tradeoffs are recorded on the Epic so the "done" is honest and auditable.

The Epic-comparison moment → the joint-debug trigger

After agents report their work done, the delivered whole is compared against the Epic. Two classes of gap:

• A listed must-have isn't shipped → reopen the under-delivering task, or add a new task for the missing piece (see §3).
• A quality/design gap or a "we couldn't fix X" situation → this is the natural moment to exec: the user drops into the agent's workspace and does a joint debugging session (the pi / Claude-Code live experience), working the hard problem together rather than accepting a reduction or filing more async work.

So "deliver → compare → gap" routes not only to reopen/new-task, but also to live collaboration — giving exec a concrete, principled trigger point that round 2 noted was missing (LE-10 / LE-4 boundary).

---

2. The data model — project resources

Three project-scoped resources:

Epic (the vision — its own resource, §1)
  └── epictask  — a roadmap node; tasks hang off it
        ├── task — the unit of work / execution
        └── task
  └── epictask ── chains to other epictasks (the roadmap web)

epictask

• A roadmap node. Tasks link to an epic task (a task belongs-to / serves an epic task).
• Epic tasks chain to each other (dependencies). Visualizing all epic tasks yields a spider web of roadmap — not a flat sequence, but a dependency graph. This is the navigational/planning layer.

task

• The unit of work, owned by an epictask.
• Carries the standard lifecycle from round 1 (InProgress → SelfCheck → AwaitingReview → accept → Merged → Reopened-on-failure).
• Contains artifacts (see §4).

Threading the vision through

Because tasks link to epictasks and epictasks belong to an Epic, every task can resolve "what am I serving and what does done-for-this look like" by walking up the chain to the Epic + its agreed "done" criteria. Tier-2 (vision) DoD is therefore reachable from every task, not bolted on.

---

3. Reopen vs new-task — the mechanism

The Epic-comparison diff produces both, distinguished by why the gap exists:

Gap cause	Outcome
A task claimed to cover a piece but didn't deliver it right (acceptance criteria unmet)	Reopen the task (send back with the directional comment)
A piece of the Epic was never decomposed into a task at all (breakdown gap)	New task under the relevant epictask
A piece needs joint effort / the fix is hard	exec joint session (plus optionally reopen/new task after)

The loop repeats until the Epic reaches a terminal state: 100% delivered, or delivered-with-accepted-tradeoffs.

---

4. Artifacts + IPython-style context (prime-agent philosophy)

Borrowing from PrimeIntellect prime-agent's "context as variables / prompt-as-a-variable" model:

Artifacts are objects, not plain text

Each task can contain artifacts: files|test, logs, and also PR and commits — but as structured objects with an expand operation, not stored/loaded as plain text.

• A PR or commit is an object; the LLM can expand it on demand to get the detail (diff, files, messages). It is not dumped into context eagerly.
• "Catting" something materializes it into a variable/artifact — a named, retrievable reference — rather than auto-injecting its full text into the LLM context.

The rule: context does NOT auto-populate from artifact content. You pull what you need; nothing is eagerly loaded.

Eviction / flush priority (what to drop first)

When context must be flushed/compacted, the retention hierarchy is:

1. Keep the user's words the longest — highest retention.
2. Next, keep what the agent said.
3. Next, the artifact context — and this is safe to evict first because artifacts are durably stored; their content can always be recovered on demand via expand.

So eviction order is user > agent > artifact-context, justified precisely by recoverability: artifact content isn't lost, it's retrievable — so dropping it from live context costs nothing permanent.

---

5. Open questions / tensions to resolve

1. Epic as a resource vs a "prompt" — does the Epic get its own resource type (with RBAC + ResourceRevision), or reuse the project prompt/skill mechanism? Lean: own resource — it's the audit/source-of-truth for "is this done," distinct from context-injection prompts.
2. Epic-task done criteria — do epictasks also carry their own acceptance criteria, or is all "done" defined at the Epic level? Lean: Epic defines overall done; epictasks carry the decomposed subset, so the spider web can show per-node completeness.
3. Artifact storage location — consistent with LE-8/LE-5: server-side, mcpctl-owned, keyed by commit/task. Confirm artifacts live outside git (for binaries/build outputs) vs git-native for commits/PRs (which stay in the repo/PR API and are referenced as objects, not copied).
4. What counts as "artifact context" for eviction — an expanded artifact that has been pulled into context: once the turn ends, does it return to "stored-only" (safe to evict) or persist as agent-context? Lean: after the turn it is stored-only again (evict first), because it's recoverable.
5. Naming (LE-7) — epictask vs epic-task vs epic_task; and whether task collides with the repo's .taskmaster tasks. Needs a naming decision.