First-class Artifact Links on Tasks

SpecDraftJAM-16Created Apr 4, 202610 min readFull screen ↗

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

Task model has no artifacts field
Artifact-task links exist only as markdown URLs in the task description field
JAM-30 (approved, up-next) proposes adding a task field to artifact frontmatter for the artifacts page
Known tasks with manually pasted artifact links: JAM-5, JAM-6, JAM-7, JAM-9, JAM-11, JAM-14, JAM-15, JAM-18, JAM-25, JAM-30
No visual indicator on task cards for whether artifacts exist
Task editor has no artifact management UI

4. Platform Capabilities

MC already has:

Artifact frontmatter parsing (title, type, status, tags)
Task data model in tasks.json
Task detail/editor view
Board and list card components

JAM-30 will add:

task field in artifact frontmatter (the artifact declares which task it belongs to)
Artifact cards with task badges on the artifacts page

What's missing:

Task-side rendering of linked artifacts (reading from frontmatter)
Artifact management UI on tasks
Card-level artifact indicator

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):

Artifact frontmatter scanner

API endpoint or server-side function that reads all artifact frontmatter
Returns a map of taskDisplayId → [artifact metadata]
Cached/memoized with a reasonable TTL (artifacts don't change every second)

Artifacts section in task detail view

Renders linked artifacts as compact pills (type dot + title)
Handles 1-3 inline, 4+ with collapse/expand
Click opens artifact page
Shows "No artifacts" or simply omits the section when none are linked

Task card artifact indicator

Small icon on board and list cards when artifacts exist
Uses the same scanner/cache as the detail view

Migration: clean up markdown artifact links

For tasks where artifact links are in the Details field AND the artifact frontmatter already has the task field set, remove the redundant markdown links from Details
Only remove clearly standalone artifact link sections, not links embedded in prose
Back up tasks.json before migration

11. Validation Criteria

Task detail view shows linked artifacts from frontmatter data
Artifacts page shows task badges (JAM-30 provides this)
Changing an artifact's task field updates both views
Removing the task field disconnects the artifact from both views
Task cards show artifact indicator when linked artifacts exist
Tasks with no linked artifacts render normally (no empty section, no errors)
Existing markdown links cleaned up where safe

12. Test Plan

Test 1: Forward link (artifact → task detail)

Set task: JAM-18 in an artifact's frontmatter
Open JAM-18 in the task detail view
Pass: Artifact appears in the Artifacts section as a clickable pill

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

Same artifact from Test 1
Open the artifacts page
Pass: Artifact card shows "JAM-18" badge (provided by JAM-30)

Test 3: Disconnect

Remove the task field from the artifact's frontmatter
Reload task detail and artifacts page
Pass: Artifact no longer appears in either view

Test 4: Multiple artifacts per task

Set task: JAM-11 on 3 different artifacts
Open JAM-11 in task detail
Pass: All 3 appear in the Artifacts section

Test 5: Many artifacts (collapse behavior)

Set task: JAM-11 on 6+ artifacts
Open JAM-11 in task detail
Pass: Shows 2-3 inline with "+N more" that expands on click

Test 6: Card indicator

On the board, find a task that has linked artifacts
Pass: Small document icon visible on the card
Find a task with no linked artifacts
Pass: No icon

Test 7: Migration cleanup

After migration, open a task that previously had markdown artifact links in Details
Pass: Standalone artifact link sections removed, artifacts appear in dedicated section instead
Prose-embedded links preserved if removal would break readability

13. Category

Tool - data model and UI improvement to existing task system

14. Context Loading

Build time: this spec + JAM-30 spec (for shared data model) + current artifact frontmatter schema
Runtime: artifact frontmatter scan + task detail view rendering

15. Guardrails

Do not add an artifacts[] field to the task data model. Frontmatter is the source of truth.
Do not build artifact management UI on the task editor in v1. Keep the data flow one-directional.
Never write null for any task field during migration.
Back up both tasks.json and artifacts/ directory before migration.
JAM-16 depends on JAM-30 shipping first (the task field in frontmatter must exist before we can read it).

16. Handoff

JAM-30 ships first (creates task field in frontmatter, builds artifacts page)
David then builds task-side rendering and card indicators (JAM-16)
Vinny validates two-way navigation and runs test plan
Vinny moves to needs-review, assigns to Pete