alexion/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(wayfinder): add artifact-backed planning skill

Browse Source
This commit is contained in:
alexion
2026-07-31 10:35:25 -04:00
parent 7550096968
commit 4da2452084
2 changed files with 229 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
skills/wayfinder/ARTIFACTS.md Normal file
View File

@@ -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/<project>/` 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: `<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 an index rather than the store for ticket resolutions.
```markdown
# <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>]]
## Resolutions so far
<one entry per resolved ticket, linking to the canonical result>
## Not yet specified
<in-scope fog that is not precise enough to ticket>
## Out of scope
<work consciously ruled beyond the destination>
```
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: "[[<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 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.

97
skills/wayfinder/SKILL.md Normal file
View File

@@ -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.