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

Unify Wayfinder ticket artifacts

Browse Source
This commit is contained in:
alexion
2026-07-31 20:38:27 -04:00
parent b5c6e33730
commit 012a4bfd1e
4 changed files with 24 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
skills/prototype/SKILL.md
View File

@@ -61,11 +61,13 @@ Use the naming convention declared there, or infer it from nearby artifacts when
Do not assume a counter, numeric prefix, slug shape, or artifact-type suffix unless the destination convention requires it. Do not assume a counter, numeric prefix, slug shape, or artifact-type suffix unless the destination convention requires it.
If no convention can be determined, choose the least surprising lowercase descriptive Markdown filename and state that the destination did not define a naming convention. If no convention can be determined, choose the least surprising lowercase descriptive Markdown filename and state that the destination did not define a naming convention.
When the caller provides an allocated filename and `parent`, use them exactly and do not advance any counter. When the caller provides an existing ticket artifact path, use it exactly, do not allocate a filename, and complete that artifact in place.
Create only the Prototype artifact and leave the parent artifact unchanged.
Otherwise, allocate any identifier required by the destination convention and include `parent` only when an earlier artifact directly caused the prototype. Otherwise, allocate any identifier required by the destination convention and include `parent` only when an earlier artifact directly caused the prototype.
The Prototype artifact links the throwaway branch and preserves the question, run instructions, verdict, and branch-appropriate evidence: The Prototype artifact links the throwaway branch and preserves the question, run instructions, verdict, and branch-appropriate evidence.
When the resolved file is an existing ticket artifact, preserve its workflow metadata and complete the result in that file.
The branch-appropriate evidence is:
- UI evidence uses screenshots. - UI evidence uses screenshots.
- Logic evidence uses useful code snippets and, where needed, a short interaction transcript. - Logic evidence uses useful code snippets and, where needed, a short interaction transcript.

6
skills/research/SKILL.md
View File

@@ -22,11 +22,10 @@ Use the naming convention declared there, or infer it from nearby artifacts when
Do not assume a counter, numeric prefix, slug shape, or artifact-type suffix unless the destination convention requires it. Do not assume a counter, numeric prefix, slug shape, or artifact-type suffix unless the destination convention requires it.
If no convention can be determined, choose the least surprising lowercase descriptive Markdown filename and state that the destination did not define a naming convention. If no convention can be determined, choose the least surprising lowercase descriptive Markdown filename and state that the destination did not define a naming convention.
When the caller provides an allocated filename and `parent`, use them exactly and do not advance any counter. When the caller provides an existing ticket artifact path, use it exactly, do not allocate a filename, and complete that artifact in place.
Create only the Research artifact and leave the parent artifact unchanged.
Otherwise, allocate any identifier required by the destination convention and include `parent` only when an earlier artifact directly caused the research. Otherwise, allocate any identifier required by the destination convention and include `parent` only when an earlier artifact directly caused the research.
Done when one authoritative output path and its metadata are settled according to the destination convention. Done when one authoritative Research artifact path and its metadata are settled according to the destination convention.
## 2. Investigate the question ## 2. Investigate the question
@@ -40,6 +39,7 @@ Done when the question is answered as far as primary evidence permits and every
## 3. Write the Research artifact ## 3. Write the Research artifact
Write the findings to the resolved Markdown file and follow the destination's artifact conventions. Write the findings to the resolved Markdown file and follow the destination's artifact conventions.
When the resolved file is an existing ticket artifact, preserve its workflow metadata and complete the result in that file.
Keep the question, findings, limitations, and citations sufficient for a future reader to evaluate the result without reconstructing the research session. Keep the question, findings, limitations, and citations sufficient for a future reader to evaluate the result without reconstructing the research session.
Do not create a source dump or research log. Do not create a source dump or research log.

16
skills/wayfinder/ARTIFACTS.md
View File

@@ -20,6 +20,8 @@ If no convention can be determined, choose the least surprising lowercase descri
Refer to artifacts through the link style used by the destination. Refer to artifacts through the link style used by the destination.
Never use a bare identifier as a human-facing reference. Never use a bare identifier as a human-facing reference.
Ticket filenames use the substantive artifact type as their artifact-type suffix: `research`, `prototype`, `grill`, or `task`.
Do not use `ticket` as a filename artifact-type suffix.
## Map ## Map
@@ -70,7 +72,7 @@ Order Frontier links by the destination's declared ordering unless the user choo
Fall back to filename order when no ordering is declared. Fall back to filename order when no ordering is declared.
Under **Decisions so far**, record one concise, self-contained decision for each resolved 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. Do not link or identify the resolved ticket, or copy supporting detail from the canonical resolution into the map.
## Tickets ## Tickets
@@ -108,7 +110,7 @@ An artifact may have many children, which agents find by searching for backlinks
`blocked-by` records zero or more upstream artifacts that must resolve before the ticket becomes actionable. `blocked-by` records zero or more upstream artifacts that must resolve before the ticket becomes actionable.
It is independent of `parent`. It is independent of `parent`.
A ticket blocker is satisfied when its status is `resolved`. A ticket blocker is satisfied when its status is `resolved`.
A non-ticket result blocker is satisfied when its artifact exists. A non-ticket 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. A ticket is on the Frontier when its status is `open`, every blocker is satisfied, and it has no claim.
## Claims and status ## Claims and status
@@ -130,12 +132,12 @@ An out-of-scope ticket is closed, while **Out of scope** states the excluded wor
## Results ## Results
A Grill or Task ticket stores its canonical result under a `## Resolution` section in that ticket. A ticket is a self-resolving artifact.
Research and Prototype tickets leave their question in the ticket and store the result in a child artifact whose `parent` points to the ticket. Its canonical result lives in that same artifact rather than in a child result artifact.
When invoking `research` or `prototype`, provide the resolved artifact destination, the filename chosen from that destination's convention, and the ticket link that the result must use as its `parent`. When invoking `research` or `prototype`, provide the resolved ticket artifact path.
The called skill creates the result artifact but does not edit the ticket or map. The called skill completes the ticket artifact in place and does not edit the map.
The coordinating Wayfinder agent validates the returned artifact, marks the ticket resolved, and updates the map. The coordinating Wayfinder agent validates the updated ticket artifact, marks the ticket resolved when the called skill has not already done so, 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. 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. Navigate the artifact journey forward by finding every note whose `parent` links to the current artifact.

14
skills/wayfinder/SKILL.md
View File

@@ -35,9 +35,9 @@ A HITL ticket only resolves through that exchange.
The agent never speaks for the human's side. The agent never speaks for the human's side.
- **Research** (AFK): Investigate documentation, third-party APIs, or resources outside the current working directory through `research`. - **Research** (AFK): Investigate documentation, third-party APIs, or resources outside the current working directory through `research`.
The called skill creates a Research artifact and Wayfinder integrates it. The called skill completes the Research ticket artifact in place.
- **Prototype** (HITL): Raise the fidelity of a logic, state-model, or UI decision through `prototype`. - **Prototype** (HITL): Raise the fidelity of a logic, state-model, or UI decision through `prototype`.
The called skill creates a Prototype artifact and Wayfinder integrates it after the human reaches a verdict. The called skill completes the Prototype ticket artifact in place after the human reaches a verdict.
- **Grill** (HITL): Resolve a decision through `grill`. - **Grill** (HITL): Resolve a decision through `grill`.
This is the default ticket type. This is the default ticket type.
- **Task** (AFK or HITL): Perform prerequisite work that must happen before a decision can be made. - **Task** (AFK or HITL): Perform prerequisite work that must happen before a decision can be made.
@@ -86,9 +86,9 @@ Never resolve more than one non-Research ticket in a session.
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. 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.** 4. **Dispatch Research.**
Invoke `research` for each Research ticket using whatever isolation or concurrency the caller provides. Invoke `research` for each Research ticket using whatever isolation or concurrency the caller provides.
Integrate each returned Research artifact according to [`ARTIFACTS.md`](ARTIFACTS.md). Reconcile each completed Research ticket according to [`ARTIFACTS.md`](ARTIFACTS.md).
Leave a ticket open with the reason visible when its Research run cannot complete. Leave a ticket open with the reason visible when its Research run cannot complete.
Done when every dispatched result is integrated or every incomplete Research ticket records why it remains open. Done when every dispatched Research ticket is resolved or records why it remains open.
5. **Stop.** 5. **Stop.**
Stop without resolving a HITL ticket. Stop without resolving a HITL ticket.
Done when charting has created and dispatched the visible route without consuming its human decision work. Done when charting has created and dispatched the visible route without consuming its human decision work.
@@ -110,9 +110,9 @@ Never resolve more than one non-Research ticket in a session.
Load related artifacts only when needed. Load related artifacts only when needed.
Done when the question has a resolution or the prerequisite Task is complete. Done when the question has a resolution or the prerequisite Task is complete.
4. **Record the resolution.** 4. **Record the resolution.**
Persist the canonical result, resolve the ticket, and append its concise decision under the map's **Decisions so far** according to [`ARTIFACTS.md`](ARTIFACTS.md). Persist the canonical result in the ticket artifact, resolve the ticket, and append its concise decision under the map's **Decisions so far** according to [`ARTIFACTS.md`](ARTIFACTS.md).
Do not link or identify the resolved ticket or its result artifacts from the map. Do not link or identify the resolved ticket from the map.
Done when the resolution lives in exactly one canonical place and the map states only the resulting decision. Done when the resolution lives in the ticket artifact and the map states only the resulting decision.
5. **Advance the frontier.** 5. **Advance the frontier.**
Create tickets surfaced by the resolution and wire their blockers. Create tickets surfaced by the resolution and wire their blockers.
Graduate newly precise fog, remove invalidated tickets, move beyond-destination work out of scope, and recompute the Frontier. Graduate newly precise fog, remove invalidated tickets, move beyond-destination work out of scope, and recompute the Frontier.