# 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](https://github.com/PrimeIntellect-ai/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 `expand`ed 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.