From 4da24520846f4159b1c565cd6689fc0c9e2b01f2 Mon Sep 17 00:00:00 2001 From: alexion Date: Fri, 31 Jul 2026 10:35:25 -0400 Subject: [PATCH] feat(wayfinder): add artifact-backed planning skill --- skills/wayfinder/ARTIFACTS.md | 132 ++++++++++++++++++++++++++++++++++ skills/wayfinder/SKILL.md | 97 +++++++++++++++++++++++++ 2 files changed, 229 insertions(+) create mode 100644 skills/wayfinder/ARTIFACTS.md create mode 100644 skills/wayfinder/SKILL.md diff --git a/skills/wayfinder/ARTIFACTS.md b/skills/wayfinder/ARTIFACTS.md new file mode 100644 index 0000000..681843a --- /dev/null +++ b/skills/wayfinder/ARTIFACTS.md @@ -0,0 +1,132 @@ +# 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//` when a new project first needs a map. +Keep the project directory flat. + +Allocate every new artifact through the vault-root `.counter`. +The coordinating Wayfinder agent reconciles duplicate identifiers after concurrent workers return. + +## Names + +Use an effort slug that identifies one durable effort and is not reused for another map in the project. +Use these filenames: + +- Map: `--map.md` +- Ticket: `---ticket.md` +- Research result: `---research.md` +- Prototype result: `---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 an index rather than the store for ticket resolutions. + +```markdown +# + +## Destination + + + +## Notes + + + +## Frontier + +- [[]] + +## Resolutions so far + + + +## Not yet specified + + + +## Out of scope + + +``` + +The Frontier is a derived navigation index. +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. + +For a resolved Grill or Task ticket, link the ticket and give a one-line gist. +For a resolved Research or Prototype ticket, give the ticket's gist once and nest links to every result artifact beneath it. +Do not copy the resolution into the map. + +## Tickets + +A new ticket starts as: + +```markdown +--- +status: open +parent: "[[]]" +blocked-by: [] +tags: + - ticket/ +--- + +# + +## Question + + +``` + +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 appear under Resolutions so far. +An out-of-scope ticket is closed and linked from Out of scope with the reason it lies beyond the destination. + +## 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 results in one or more child artifacts whose `parent` points to the ticket. +The called skill creates those result artifacts but does not edit the ticket or map. +The coordinating Wayfinder agent integrates the artifacts, marks the ticket resolved, and updates the map. + +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. diff --git a/skills/wayfinder/SKILL.md b/skills/wayfinder/SKILL.md new file mode 100644 index 0000000..dd4b1ae --- /dev/null +++ b/skills/wayfinder/SKILL.md @@ -0,0 +1,97 @@ +--- +name: wayfinder +description: Plan work too large and uncertain for one agent session as a durable map of decision tickets, then resolve one frontier ticket at a time until the route to the destination is clear. +disable-model-invocation: true +--- + +# wayfinder + +A loose idea has arrived that is too large for one agent session and too foggy to plan directly. +Wayfinding charts the decisions needed to reach a **destination**, then works those decisions one at a time until the route is clear. + +Read [`ARTIFACTS.md`](ARTIFACTS.md) before charting or working a map. +It is the sole source for how maps, tickets, claims, blocking, results, and the Frontier live in the AI artifacts vault. + +## Plan, don't do + +Wayfinder plans by default. +The map is complete when nothing remains to decide before someone performs the destination work. +The urge to implement the destination usually marks the edge of the map. +An effort may explicitly permit execution in its Notes, but otherwise preserve resolutions and hand off rather than deliver the destination. + +## Ticket types + +Every ticket is either **HITL**, worked through a live exchange with the human, or **AFK**, driven by the agent. +A HITL ticket never resolves by having the agent speak for the human. + +- **Research** (AFK): Investigate knowledge outside the current working directory through `/research`. +- **Prototype** (HITL): Create concrete Logic or UI code to react to through `/prototype`. + Within Wayfinder, stop at the verdict rather than folding the result into production. +- **Grill** (HITL): Resolve a decision through `/grill`. + This is the default ticket type. +- **Task** (AFK or HITL): Perform prerequisite work that must happen before a decision can be made. + The required capability is specific to the action. + The agent performs it where possible and otherwise gives the human a precise checklist. + +A Task earns its place by unblocking a decision, not by delivering part of the destination. + +## Fog of war + +The map is deliberately incomplete. +**Not yet specified** holds in-scope questions that are visible but cannot yet be stated precisely enough to ticket. +Create a ticket as soon as its question is precise, even when it is blocked and cannot yet be answered. +A fog entry may graduate into several tickets or disappear when an earlier resolution changes the route. + +The destination fixes scope. +Work beyond it belongs in **Out of scope**, never in fog. +If an existing ticket proves to be beyond the destination, close it as out of scope and link it from that section rather than recording it as a resolution. + +## Select the mode + +- A loose idea without a map uses **Chart the map**. +- An existing map uses **Work through the map**. + +Never resolve more than one non-Research ticket in a session. + +## Chart the map + +1. **Name the destination.** + Invoke `/grill` to settle what reaching the end of this effort looks like. + Done when the destination states the spec, decision, or change the map is finding its way toward and fixes its scope. +2. **Map breadth-first.** + Invoke `/grill` again to fan out across the whole space, identifying precise open questions, blocking relationships, and fog without drilling into any one answer. + If this surfaces no fog and the route fits one session, stop and ask how the user wants to proceed instead of creating a map. + Done when every visible in-scope uncertainty is either a precise ticket question or an honest fog entry. +3. **Create the map and tickets.** + Create the map first, then every currently precise ticket, then wire `blocked-by` relationships in a second pass according to `ARTIFACTS.md`. + Done when the map is the effort root, every precise question has one ticket, every known blocking edge is represented, and the Frontier is current. +4. **Dispatch Research.** + Invoke `/research` for each Research ticket using whatever isolation or concurrency the caller provides. + Let the coordinating Wayfinder agent integrate returned Research artifacts according to `ARTIFACTS.md`. + Done when every dispatched Research result has been integrated or every Research ticket that could not run remains open with the reason visible. +5. Stop without resolving a HITL ticket. + +## Work through the map + +1. **Orient.** + Read the map at low resolution and reconcile its derived Frontier against ticket metadata. + Done when the destination, standing Notes, prior resolutions, fog, scope boundary, and current Frontier agree with the artifacts. +2. **Claim one ticket.** + Use the user-named ticket when it is actionable, otherwise claim the first Frontier ticket. + Persist the claim before doing its work. + Done when exactly one open, unblocked ticket records this session's claim. +3. **Resolve by type.** + Invoke `/research`, `/prototype`, or `/grill` for those ticket types. + Perform a Task through the capability or human checklist it requires. + Zoom into related artifacts only as needed rather than loading the whole effort. + Done when the ticket's question has a resolution or the prerequisite Task is complete. +4. **Record the resolution.** + Persist the result, resolve the ticket, and add its gist and links under the map's Resolutions so far. + Done when the resolution lives in exactly one canonical place and the map points to it without restating it. +5. **Advance the frontier.** + Create tickets surfaced by the resolution according to `ARTIFACTS.md`. + Graduate newly precise fog, remove invalidated tickets, move beyond-destination work out of scope, and recompute the Frontier. + Done when every newly visible question has exactly one home and the map matches all current ticket metadata. + +Expect concurrent sessions to edit the same effort. +Re-read shared artifacts before each write and reconcile collisions through the vault convention.