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

feat(wayfinder): default to isolated frontier workers

Browse Source
This commit is contained in:
alexion
2026-08-01 17:52:09 -04:00
parent d758f722f9
commit 0f2b13c5f9
3 changed files with 43 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
skills/implement/SKILL.md
View File

@@ -1,6 +1,6 @@
---
name: implement
description: Implement scoped work using the local implementation workflow, following Wayfinder ticket protocol when a task artifact is part of the selected work.
description: Implement scoped work using the local implementation workflow, following Wayfinder ticket protocol when an implementation ticket artifact is part of the selected work.
disable-model-invocation: true
---
@@ -8,7 +8,7 @@ disable-model-invocation: true
Implement scoped work and hand off working code.
This skill defines execution protocol rather than deciding what work the agent is allowed to implement.
When selected work has a Wayfinder task artifact, follow the Wayfinder artifact lifecycle.
When selected work has a Wayfinder ticket artifact, follow the Wayfinder artifact lifecycle.
When selected work has no Wayfinder artifact, implement normally and use the same review, commit, and handoff discipline without creating a tracking artifact.
This skill delegates to other skills by name.
@@ -18,16 +18,16 @@ Do not satisfy a delegated skill step by imitating its title from memory.
## 1. Establish the selected work
Identify the work to implement from the user's request and current context.
Use a Wayfinder task artifact, issue, spec, direct request, branch context, or other clear source when that is what the agent has selected.
Use a Wayfinder implementation ticket artifact, issue, spec, direct request, branch context, or other clear source when that is what the agent has selected.
Do not require a Wayfinder artifact and do not create one just to satisfy this skill.
Old `.claude/tasks` files may be ordinary context, but their lifecycle semantics are not part of this workflow.
When the selected work has a Wayfinder task artifact, re-read it before claiming.
When the selected work has a Wayfinder ticket artifact, re-read it before claiming.
Verify that blockers are satisfied by the artifact metadata and that no other session has claimed it.
Claim it before changing code by setting `status: claimed`, `claimed-by` to the current session identifier, and `claimed-at` to the current timestamp.
Use `PI_SESSION_ID` when available.
Done when the selected work is clear, and any Wayfinder task artifact is freshly read and claimed when applicable.
Done when the selected work is clear, and any Wayfinder ticket artifact is freshly read and claimed when applicable.
## 2. Verify the execution checkout
@@ -75,7 +75,7 @@ Done when the selected work is implemented as working code and locally verified
## 4. Review the final intended handoff state
Load and run `review` before reporting final handoff or resolving a Wayfinder task.
Load and run `review` before reporting final handoff or resolving a Wayfinder ticket.
Choose review timing by judgment.
Review may happen before commit, after commit, or both.
The review must cover the final intended handoff state, including a local uncommitted handoff when no commit is made.
@@ -104,7 +104,7 @@ Done when the implementation has a concrete handoff state: committed locally, pu
## 6. Close out Wayfinder artifacts when present
When the selected work has a Wayfinder task artifact, re-read it before closeout.
When the selected work has a Wayfinder ticket artifact, re-read it before closeout.
Record durable coordination facts only.
Wayfinder `status` is the lifecycle authority.
Acceptance criteria checkboxes may be updated as useful detail with `[x]` for satisfied criteria and `[-]` for deliberately dropped criteria when practical.
@@ -115,8 +115,8 @@ Capture only what future agents or humans need: deviations, dropped or changed s
Use judgment for partial or ambiguous outcomes, but keep lifecycle recording honest.
Do not imply completion when the work is not complete.
When resolving a Wayfinder task, set `status: resolved` and repair the owning map's Frontier according to Wayfinder artifact rules.
Put detailed implementation records in the task ticket, commit, PR, and working code rather than in the map.
When resolving a Wayfinder ticket, set `status: resolved` and repair the owning map's Frontier according to Wayfinder artifact rules.
Put detailed implementation records in the ticket, commit, PR, and working code rather than in the map.
The parent map should receive only the concise outcome summary required by Wayfinder.
Done when any Wayfinder task and parent map agree with the implementation's actual lifecycle state.
Done when any Wayfinder ticket and parent map agree with the implementation's actual lifecycle state.

15
skills/wayfinder/ARTIFACTS.md
View File

@@ -20,7 +20,7 @@ If no convention can be determined, choose the least surprising lowercase descri
Refer to artifacts through the link style used by the destination.
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`.
Ticket filenames use the substantive artifact type as their artifact-type suffix: `research`, `prototype`, `grill`, `task`, or `implementation`.
Do not use `ticket` as a filename artifact-type suffix.
## Map
@@ -52,7 +52,7 @@ tags:
## Decisions so far
<one plain-language decision per resolved ticket, without artifact links>
<one plain-language decision or implementation outcome per resolved ticket, without artifact links>
## Not yet specified
@@ -71,7 +71,7 @@ Repair the Frontier whenever it is missing, stale, or inconsistent with ticket s
Order Frontier links by the destination's declared ordering unless the user chooses another ticket.
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 or implementation outcome for each resolved ticket.
Do not link or identify the resolved ticket, or copy supporting detail from the canonical resolution into the map.
## Tickets
@@ -91,7 +91,7 @@ tags:
## Question
<one precise question or prerequisite action sized to one agent session>
<one precise question, prerequisite action, or implementation slice sized to one agent session>
```
Use one of these tags:
@@ -102,6 +102,7 @@ Use one of these tags:
- `ticket/grill`
- `ticket/task/afk`
- `ticket/task/human`
- `ticket/implementation`
`parent` records provenance.
An initial ticket points to the map.
@@ -113,6 +114,8 @@ It is independent of `parent`.
A ticket blocker is satisfied when its status is `resolved`.
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/task/afk` ticket is prerequisite work that unblocks the route.
A `ticket/implementation` ticket is a code, configuration, documentation, or test slice that delivers part of an execution map's destination.
## Claims and status
@@ -128,7 +131,7 @@ Use `PI_SESSION_ID` when available and an equivalent harness session identifier
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**.
Only resolved tickets contribute decisions or implementation outcomes 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
@@ -136,7 +139,7 @@ An out-of-scope ticket is closed, while **Out of scope** states the excluded wor
A ticket is a self-resolving artifact.
Its canonical result lives in that same artifact rather than in a child result artifact.
When invoking `research` or `prototype`, provide the resolved ticket artifact path.
When invoking `research`, `prototype`, or `implement`, provide the resolved ticket artifact path.
The called skill completes the ticket artifact in place and does not edit 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.

39
skills/wayfinder/SKILL.md
View File

@@ -1,6 +1,6 @@
---
name: wayfinder
description: Plan a huge chunk of work that exceeds one agent session as a durable map of decision tickets, then resolve them one at a time until the way to the destination is clear.
description: Plan or coordinate a huge chunk of work that exceeds one agent session as a durable map of tickets, then resolve them until the way to the destination is clear.
disable-model-invocation: true
---
@@ -8,7 +8,7 @@ disable-model-invocation: true
A loose idea has arrived that is too large for one agent session and wrapped in fog.
Wayfinding charts the way to a **destination** rather than charging at it.
It creates a durable map of questions whose resolutions are decisions, findings, prototypes, or completed prerequisites rather than slices of the destination work.
It creates a durable map of questions whose resolutions are decisions, findings, prototypes, completed prerequisites, or explicit implementation slices.
Read [`ARTIFACTS.md`](ARTIFACTS.md) before charting or working a map.
It is the single source of truth for how maps, tickets, claims, blocking, resolutions, and the Frontier live in the resolved artifact destination.
@@ -21,7 +21,7 @@ The urge to implement the destination usually marks the edge of a planning map a
An effort may explicitly permit execution in its Notes, but otherwise preserve resolutions rather than deliver the destination.
A map may explicitly be an execution map when the destination is a tracked implementation effort rather than a route to a later handoff.
Execution maps use the same ticket, claim, and Frontier mechanics, but AFK Task tickets may deliver implementation slices.
Execution maps use the same ticket, claim, and Frontier mechanics, but implementation tickets may deliver slices of the destination.
The destination varies by effort and shapes every ticket.
It may be a spec to hand off, a decision to lock before planning, a change whose route must be understood before implementation, or an implementation effort whose slices need coordination.
@@ -45,10 +45,11 @@ The agent never speaks for the human's side.
The called skill completes the Prototype ticket artifact in place after the verdict is reached.
- **Grill** (HITL): Resolve a decision through `grill`.
This is the default ticket type.
- **Task** (AFK or HITL): Perform prerequisite work or implementation work that fits the map's destination.
- **Task** (AFK or HITL): Perform prerequisite work that fits the map's destination.
In a planning map, a Task earns its place by unblocking a decision rather than delivering part of the destination.
In an execution map, an AFK Task may deliver an implementation slice.
The agent performs it where possible and otherwise gives the human a precise checklist.
- **Implementation** (AFK): Deliver a code, configuration, documentation, or test slice of an execution map through `implement`.
Implementation tickets expect checkout verification, tests where useful, review, commit or handoff, and Wayfinder closeout.
## Fog of war
@@ -73,13 +74,16 @@ Do not record a scope boundary as a decision on the route.
- A loose idea without a map uses **Chart the map**.
- An existing map uses **Work through the map**.
- A session asked to coordinate multiple independent workers uses **Coordinate workers** inside **Work through the map**.
- A session working a map with unblocked AFK Frontier tickets uses **Coordinate workers** inside **Work through the map** when the current harness provides a real isolation or concurrency mechanism.
Worker coordination is the default for AFK Frontier work when an isolation or concurrency mechanism is available.
The current session acts as coordinator.
A worker session resolves exactly one claimed ticket and stops.
A coordinating session may dispatch multiple open Frontier tickets through whatever real isolation or concurrency mechanism the current harness provides.
A coordinating session does not claim tickets it intends to delegate.
Each worker claims its own ticket so accountability remains attached to the session doing the work.
An interactive Wayfinder session may resolve multiple tickets sequentially, but must complete the full reconcile, claim, resolve, record, and frontier-advance loop before selecting another ticket.
An interactive Wayfinder session may resolve multiple tickets sequentially only when worker coordination is unavailable, unnecessary, or explicitly not selected.
It must complete the full reconcile, claim, resolve, record, and frontier-advance loop before selecting another ticket.
Do not auto-consume HITL tickets without user participation.
## Chart the map
@@ -110,21 +114,21 @@ Do not auto-consume HITL tickets without user participation.
Read the map at low resolution rather than loading every ticket.
Reconcile its derived Frontier against ticket metadata.
Done when the destination, Notes, prior decisions, fog, scope boundary, and current Frontier agree with the artifacts.
2. **Claim one ticket.**
If coordinating workers, use **Coordinate workers** instead of claiming a ticket here.
Use the user-named ticket when it is actionable.
2. **Claim one ticket or coordinate workers.**
If unblocked AFK Frontier tickets can be delegated through a real isolation or concurrency mechanism, use **Coordinate workers** instead of claiming a ticket here.
Use the user-named ticket when it is actionable and not delegated.
Otherwise take the first Frontier ticket in the destination's declared ordering, falling back to filename order when no ordering is declared.
Persist the claim before doing any work.
Persist the claim before doing any direct work.
Done when exactly one unblocked ticket records this session's claim with `status: claimed`, or the session has switched to worker coordination without claiming delegated tickets.
3. **Resolve by type.**
Invoke `research`, `prototype`, or `grill` for the corresponding ticket type.
Invoke `research`, `prototype`, `grill`, or `implement` for the corresponding ticket type.
Perform a Task through the capability or human checklist it requires.
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, the prerequisite Task is complete, or the implementation slice has a concrete handoff state.
4. **Record the resolution.**
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).
Persist the canonical result in the ticket artifact, resolve the ticket, and append its concise decision or implementation outcome under the map's **Decisions so far** according to [`ARTIFACTS.md`](ARTIFACTS.md).
Do not link or identify the resolved ticket from the map.
Done when the resolution lives in the ticket artifact 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 or outcome.
5. **Advance the frontier.**
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.
@@ -143,14 +147,19 @@ Do not auto-consume HITL tickets without user participation.
Re-read the map and current Frontier before dispatch.
Select only open, unclaimed, unblocked AFK tickets.
Do not dispatch HITL tickets without live user participation.
Include every eligible AFK Frontier ticket unless serial execution or likely conflict requires selecting a smaller batch.
Done when every selected ticket is eligible and no selected ticket has been claimed by the coordinator.
2. **Dispatch workers.**
Send each selected worker exactly one ticket, the artifact path, the map context it needs, and the instruction to claim the ticket itself before work.
Route Research tickets through `research`, AFK Prototype tickets through `prototype`, Implementation tickets through `implement`, and AFK Task tickets through the focused task capability or checklist they require.
Use whatever real isolation or concurrency mechanism the current harness provides.
If no such mechanism exists, stop and report that worker coordination is unavailable in this runtime.
Use parallel workers when selected tickets are independent.
Use serial workers when tickets likely edit the same files, checkout, branch, or shared artifact surfaces.
Done when every selected ticket has either a launched worker or a visible dispatch failure.
3. **Join workers.**
Wait for every launched worker to finish, fail, time out, or be cancelled before treating coordination as complete.
Do not implement in the coordinator while workers are running.
Do not report final handoff while workers are still running.
Done when every launched worker has a terminal result or an explicit recovery status.
4. **Reconcile worker results.**