d24c30761b
Supporting documents folded into agentic-teams.md (the canonical unified design record), retained as historical context: - agentic-teams-review.md (round 2) - vision-fidelity.md (round 3 diagnosis + research) - epic-task-artifact-model.md (Epic/epictask/task + context philosophy) - session-summary-vision-fidelity.md (session narrative) All superseded by docs/agentic-teams.md, which remains the source of truth.
157 lines
7.1 KiB
Markdown
157 lines
7.1 KiB
Markdown
# 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.
|