Wayfinder artifacts

Resolve the project

Resolve the vault through $(xdg-user-dir DOCUMENTS)/ai-artifacts and read its AGENTS.md before any artifact write. Use the lowercase basename of the current working directory as the project slug. Create projects/<project>/ when a new project first needs a map. Keep the project directory flat.

Allocate every new artifact through the vault-root .counter.

Names

Use an effort slug that identifies one durable effort and is not reused for another map in the project. Use these filenames:

Map: <NNN>-<effort-slug>-map.md
Ticket: <NNN>-<effort-slug>-<subject-slug>-ticket.md
Research result: <NNN>-<effort-slug>-<subject-slug>-research.md
Prototype result: <NNN>-<effort-slug>-<subject-slug>-prototype.md

Refer to artifacts through bare Obsidian wikilinks such as [[042-wayfinder-session-auth-ticket]]. Never use a bare identifier as a human-facing reference.

Map

The map is the effort's root artifact and has no parent. It is a route summary rather than the store for ticket resolutions. Only the Frontier links to tickets or other artifacts.

---
status: open
tags:
  - wayfinder/map
---

# <effort name>

## Destination

<one or two lines describing what reaching the end of this map looks like>

## Notes

<standing domain, skill, and execution guidance>

## Frontier

- [[<open-unblocked-unclaimed-ticket>]]

## Decisions so far

<one plain-language decision per resolved ticket, without artifact links>

## Not yet specified

<in-scope fog that is not precise enough to ticket>

## Out of scope

<work consciously ruled beyond the destination>

Map status is open while any live ticket or fog remains and complete when neither remains.

The Frontier is a derived navigation index and the map's only artifact-link section. Ticket metadata is authoritative. Repair the Frontier whenever it is missing, stale, or inconsistent with ticket state. Order Frontier links by artifact identifier unless the user chooses another ticket.

Under Decisions so far, record one concise, self-contained decision for each resolved ticket. Do not link the ticket or its result artifacts, identify the ticket, or copy supporting detail from the canonical resolution into the map.

Tickets

A new ticket starts as:

---
status: open
parent: "[[<map-or-surfacing-ticket>]]"
blocked-by: []
tags:
  - ticket/<type>
---

# <ticket name>

## Question

<one precise question or prerequisite action sized to one agent session>

Use one of these tags:

ticket/research
ticket/prototype
ticket/grill
ticket/task/afk
ticket/task/human

parent records provenance. An initial ticket points to the map. A ticket surfaced by another ticket points to the surfacing ticket. An artifact may have many children, which agents find by searching for backlinks to its wikilink.

blocked-by records zero or more upstream artifacts that must resolve before the ticket becomes actionable. It is independent of parent. A ticket blocker is satisfied when its status is resolved. A non-ticket result blocker is satisfied when its artifact exists. A ticket is on the Frontier when its status is open, every blocker is satisfied, and it has no claim.

Claims and status

Ticket status is one of:

open
claimed
resolved
out-of-scope

Claim a ticket by setting status: claimed, claimed-by to the current execution-session identifier, and claimed-at to the current timestamp before doing any work. Use PI_SESSION_ID when available and an equivalent harness session identifier otherwise. Claims do not expire automatically. The acting agent uses the available context to recover an abandoned claim.

Only resolved tickets contribute decisions under Decisions so far. An out-of-scope ticket is closed, while Out of scope states the excluded work and reason in plain language without linking or identifying the ticket.

Results

A Grill or Task ticket stores its canonical result under a ## Resolution section in that ticket. Research and Prototype tickets leave their question in the ticket and store the result in a child artifact whose parent points to the ticket.

When invoking research or prototype, provide the project artifact directory, allocated filename, and ticket wikilink that the result must use as its parent. The called skill creates the result artifact but does not edit the ticket or map. The coordinating Wayfinder agent validates the returned artifact, marks the ticket resolved, and updates the map. If a called skill cannot honor this artifact contract, leave the ticket unresolved and record the incompatibility instead of silently storing the result elsewhere.

Navigate the artifact journey forward by finding every note whose parent links to the current artifact. Do not duplicate those relationships through per-artifact Next sections.

Concurrent writes

Re-read every shared artifact immediately before editing it. After concurrent workers return, detect duplicate identifiers, preserve pre-existing artifacts, renumber current outputs, update their wikilinks, and advance .counter as required by the vault convention. Recompute the Frontier only after returned artifacts and ticket states have been reconciled.

5.2 KiB Raw Blame History