spec

First-class Artifact Links on Tasks

2026-04-04

First-class Artifact Links on Tasks

1. Problem Statement and Goal

Problems

1. I have to dig through prose to find a task's artifacts. When I open a task, its related artifacts are buried as markdown links somewhere inside the Details field. Sometimes they're at the top, sometimes at the bottom, sometimes wrapped in a sentence. There's no consistent place to look, so I end up scanning the whole description just to find a link I know exists. The relationship between a task and its artifacts should be immediately visible, not hidden in freeform text.

2. The connection between artifacts and tasks is fragile. Right now the only link between a task and its artifact is a markdown URL that someone manually typed into a text field. If I edit the Details to add notes, I might accidentally delete or break the link. If I rewrite the description, I have to remember to preserve the URLs. There's no structural protection for what is actually an important relationship.

3. I can't tell from a task card whether it has artifacts at all. On the board or list view, every task card looks the same whether it has zero artifacts or five. I have to click into the task to discover if a spec or research brief exists. When I'm scanning the board to decide what to work on next, knowing whether a task already has a spec is valuable context I'm missing at a glance.

4. Artifacts and tasks reference each other, but there's no single source of truth. JAM-30 proposes adding a task field to artifact frontmatter so the artifacts page can show which task an artifact belongs to. If we also store an artifacts[] array on tasks, we're maintaining the same relationship in two places. When someone disconnects an artifact from a task, which side gets updated? When they drift out of sync (and they will), which one is correct? Two sources of truth for one relationship is a maintenance problem waiting to happen.

5. If a task accumulates many artifacts, the detail view will get cluttered. A long-running task like the kanban board (JAM-11) could easily have a spec, a research brief, multiple revision specs, and reference docs. If every linked artifact is a full-size pill or card in the detail view, the metadata section will overwhelm the actual task content. The design needs to handle the common case (1-3 artifacts) cleanly while degrading gracefully when there are more.

Goal

Artifact-to-task relationships should be structured data with one source of truth, visible at a glance on both the task board and the artifacts page, and maintainable without editing prose. When I open a task, I should see its artifacts immediately. When I view an artifact, I should see its task. One relationship, stored once, rendered in both directions.

2. Success Metric

When I'm on the board scanning tasks, I can tell which ones have specs or research behind them without clicking into any of them. When I open a task, its artifacts are right there in a dedicated section, not buried in markdown. When I disconnect an artifact from a task, it's a single action and both the task view and the artifacts page reflect the change immediately.

3. Current State

4. Platform Capabilities

MC already has:

JAM-30 will add:

What's missing:

5. Community Patterns

Linear uses linked issues as structured relationships. GitHub uses issue references that work bidirectionally from a single mention. Notion uses relation fields where one side is the source of truth and the other is a computed rollup. The pattern that works: store the relationship once, compute the reverse view.

6. Options

Option A: Artifact frontmatter owns the relationship (complement JAM-30)

Artifacts declare their task via the task field in frontmatter (already proposed in JAM-30). The task detail view reads all artifact frontmatter at render time to find linked artifacts. No artifacts[] field on tasks. One source of truth.

Pros: Single source of truth. No sync problem. Disconnecting means editing one file. Aligns with JAM-30's data model. Cons: Task detail view needs to scan artifact frontmatter (minor perf cost with 24 files, negligible). Can't link artifacts that live outside the artifacts/ directory.

Option B: Tasks own the relationship

Add artifacts[] to the task model. Task editor manages the list. Artifacts page reads task data for reverse links.

Pros: Task is the natural "container" for related work. Cons: Conflicts with JAM-30's task field approach. Two sources of truth if both specs ship. Artifact frontmatter becomes stale.

Option C: Both sides store it, with sync logic

Store on both sides, write sync logic to keep them consistent.

Pros: Both sides are independently queryable. Cons: Sync logic is a maintenance burden. Drift is inevitable. Solving a problem we created by storing the same data twice.

7. Recommendation

Option A. Artifact frontmatter is the single source of truth. This complements JAM-30 directly: JAM-30 builds the artifacts page using the task field, and JAM-16 builds the task-side view by reading that same field in reverse.

How it works

Data model: No change to task model. The task field in artifact frontmatter (from JAM-30) is the relationship. Example:

yaml
---
title: "Workspace Backup & Version Control"
type: spec
task: JAM-18
---

Task detail view: At render time, scan all artifact frontmatter files. Any artifact whose task field matches the current task's displayId is a linked artifact. Display them in a dedicated Artifacts section.

Artifacts page (JAM-30): Already reading the task field to show task badges. No change needed.

Disconnecting: Edit the artifact's frontmatter to remove or change the task field. Both views update automatically because they read from the same source.

Multiple artifacts per task: Naturally supported. Multiple artifacts can declare task: JAM-11. The task detail view shows all of them.

Multiple tasks per artifact: Not supported in v1 (the task field is a single value). If needed later, the field could become an array. For now, one artifact belongs to one task.

Task detail UI

Artifacts section (between title and metadata, always visible):

For 1-3 artifacts:

Artifacts
[ ● Spec: Workspace Backup ]  [ ● Brief: Linear Research ]

Compact pills showing type icon + truncated title. Click opens the artifact.

For 4+ artifacts:

Artifacts (7)
[ ● Spec: Workspace Backup ]  [ ● Brief: Linear Research ]  [+5 more]

Shows first 2-3, then a "+N more" pill that expands to show the rest. Keeps the detail view clean for the common case while handling accumulation gracefully.

Task card indicator

On board and list cards, show a small document icon (📄 or a subtle paperclip) next to the task title when at least one artifact is linked. No count, no details. Just a signal that artifacts exist.

Artifact management

Adding a link: Create or edit the artifact file, set task: JAM-XX in frontmatter. No UI needed beyond what JAM-30 provides. Vinny and David already create artifacts with frontmatter as part of the spec workflow.

Removing a link: Edit the artifact frontmatter to remove the task field. For v1, this is a file edit. A future enhancement could add a "disconnect" button in the task detail UI that writes to the frontmatter via API.

Why no add/remove UI on the task editor: The relationship lives in artifact files, not task data. Adding a UI to manage it from the task side would require the task editor to write to artifact files, which inverts the data flow. Keep it simple: artifacts declare their task, the task view just reads.

8. Security Considerations

None. Same data, same access. Artifact frontmatter is already readable by MC.

9. Pete's Setup Checklist

None.

10. Implementation Scope

David builds (after JAM-30 ships the task field in frontmatter):

  1. Artifact frontmatter scanner
  1. Artifacts section in task detail view
  1. Task card artifact indicator
  1. Migration: clean up markdown artifact links

11. Validation Criteria

12. Test Plan

Test 2: Reverse link (task badge on artifacts page)

Test 3: Disconnect

Test 4: Multiple artifacts per task

Test 5: Many artifacts (collapse behavior)

Test 6: Card indicator

Test 7: Migration cleanup

13. Category

Tool - data model and UI improvement to existing task system

14. Context Loading

15. Guardrails

16. Handoff