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

refactor(skills): remove wayfinder workflow

Browse Source
This commit was merged in pull request #20.
This commit is contained in:
alexion
2026-08-22 23:22:51 -04:00
parent 9b2a6bcd58
commit 9a1d21da4d
8 changed files with 53 additions and 397 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
AGENTS.md
View File

@@ -32,5 +32,3 @@ The domain glossary lives at `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/sk
Customize only the surfaces required to fit the local workflow rather than turning incidental choices into new contracts.
- The installed `gitea-axi pr view` does not support `--fields`.
Use plain `gitea-axi pr view <number>`.
- Wayfinder `ticket/task/human` tickets can still be implementation work.
They are blocked only at the point where human input is required.

35
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 an implementation ticket artifact is part of the selected work.
description: Implement scoped work using the local implementation workflow, following task artifact protocol when an implementation task artifact is part of the selected work.
disable-model-invocation: true
---
@@ -8,8 +8,8 @@ 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 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.
When selected work has an implementation task artifact, follow the task artifact lifecycle.
When selected work has no task 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.
Before satisfying a delegated skill step, explicitly load that skill's `SKILL.md` with `read` unless the harness has already injected that skill's full content into the current context.
@@ -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 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.
Use an implementation task artifact, issue, spec, direct request, branch context, or other clear source when that is what the agent has selected.
Do not require a task 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 ticket artifact, re-read it before claiming.
Verify that blockers are satisfied by the artifact metadata and that no other session has claimed it.
When the selected work has an implementation task artifact, re-read it before claiming.
Verify that blockers are satisfied by 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 ticket artifact is freshly read and claimed when applicable.
Done when the selected work is clear, and any implementation task 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 ticket.
Load and run `review` before reporting final handoff or resolving an implementation task artifact.
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.
@@ -83,7 +83,7 @@ Do not report final handoff until review has run or you have explained why revie
Fix blocking review findings unless the agent or user explicitly accepts them.
When code changes are made in response to review, rerun `review` on the relevant change set.
Record accepted blocking findings in the final handoff or Wayfinder closeout when they affect a future reader's decision to trust or continue the work.
Record accepted blocking findings in the final handoff or task artifact result when they affect a future reader's decision to trust or continue the work.
Handle non-blocking findings by judgment.
Fix them when cheap or high-value, and otherwise report or record only when useful.
@@ -102,21 +102,20 @@ Keep PR and handoff text focused on what was built, verification, review disposi
Done when the implementation has a concrete handoff state: committed locally, pushed, opened as a PR, or stopped with the exact remaining human action reported.
## 6. Close out Wayfinder artifacts when present
## 6. Record task artifact results when present
When the selected work has a Wayfinder ticket artifact, re-read it before closeout.
When the selected work has an implementation task artifact, re-read it before recording results.
Record durable coordination facts only.
Wayfinder `status` is the lifecycle authority.
The `status` field 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.
Checkbox state is not the source of truth.
Keep Implementation Notes concise.
Capture only what future agents or humans need: deviations, dropped or changed scope, verification, branch, commit, PR, or why the ticket remains unresolved.
Capture only what future agents or humans need: deviations, dropped or changed scope, verification, branch, commit, PR, or why the task remains unresolved.
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 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.
When resolving an implementation task artifact, set `status: done`.
Put detailed implementation records in the task, commit, PR, and working code.
Done when any Wayfinder ticket and parent map agree with the implementation's actual lifecycle state.
Done when any implementation task artifact agrees with the implementation's actual lifecycle state.

6
skills/prototype/SKILL.md
View File

@@ -66,11 +66,11 @@ 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.
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 existing ticket artifact path, use it exactly, do not allocate a filename, and complete that artifact in place.
When the caller provides an existing artifact path, use it exactly, do not allocate a filename, and complete that artifact in place.
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.
When the resolved file is an existing ticket artifact, preserve its workflow metadata and complete the result in that file.
When the resolved file is an existing artifact, preserve its workflow metadata and complete the result in that file.
The branch-appropriate evidence is:
@@ -81,7 +81,7 @@ Done when the complete prototype is committed outside main and exactly one Proto
## 4. Fold in the decision when permitted
A planning-only caller such as Wayfinder stops after the verdict and leaves production code unchanged.
A planning-only caller stops after the verdict and leaves production code unchanged.
Otherwise, fold the validated decision into production only when the caller permits implementation.
Follow the selected branch's **Production mapping** and keep all other throwaway code out of main.

2
skills/review/SKILL.md
View File

@@ -7,7 +7,7 @@ description: Produce a structured, report-only review of a context-selected chan
Review a change set selected from context and produce a structured review report.
This skill is standalone and context-driven.
It does not know about implementation lifecycle, Wayfinder claiming, task resolution, PR creation, or ticket closeout.
It does not know about implementation lifecycle, task claiming, task resolution, PR creation, or task result recording.
It must not edit code.
Reviewer prompts live under [`reviewers/`](reviewers/).

2
skills/review/reviewers/intent.md
View File

@@ -4,7 +4,7 @@ Review only whether the selected change set satisfies the apparent intent.
Do not make Risk, Standards, Evidence, or Documentation findings unless the issue directly changes intent fidelity.
Use the clearest available intent source from context.
Possible sources include a Wayfinder task, issue, spec, direct request, PR description, branch context, commit messages, or conversation context.
Possible sources include an implementation task artifact, issue, spec, direct request, PR description, branch context, commit messages, or conversation context.
Do not invent requirements.
When intent is inferred rather than explicit, say so and treat it with appropriate caution.

73
skills/slice/SKILL.md
View File

@@ -1,26 +1,25 @@
---
name: slice
description: Turn a settled plan, spec, conversation, or artifact into Wayfinder implementation tickets for tracer-bullet slices. Run deliberately as /skill:slice when the user asks to slice work.
description: Turn a settled plan, spec, conversation, or artifact into AI-artifacts implementation tasks for tracer-bullet slices. Run deliberately as /skill:slice when the user asks to slice work.
disable-model-invocation: true
---
# slice
Turn settled source material into implementation-ready Wayfinder tickets.
Turn settled source material into implementation-ready task artifacts.
Use this when the user asks to slice a plan, spec, conversation, or artifact into agent-grabbable implementation work.
Do not use this to resolve planning fog.
If the source contains unresolved decisions, report them instead of inventing implementation slices.
`slice` writes Wayfinder `ticket/implementation` artifacts for implementation slices and `ticket/task/human` artifacts only when the slice cannot proceed without human action.
`slice` writes AI-artifacts `task/implementation` artifacts for implementation slices.
It does not write legacy `.claude/tasks/` files.
## 1. Gather source material
Work from the current conversation first.
If the caller passes paths, artifact links, issue references, or URLs, read the referenced body and relevant comments or nearby artifact context before slicing.
When source material names a Wayfinder artifact, use that artifact as the default provenance parent.
When no source artifact exists, use the active Wayfinder map if one is clear from context.
When neither exists, create or select the minimal Wayfinder parent required by the destination's artifact rules before writing tickets.
When source material names an artifact, use that artifact as the default provenance parent.
When no source artifact exists, use `parent: null` unless the destination's artifact rules require a parent.
Explore the codebase when the current implementation state is not already understood.
Use the project's established vocabulary and respect relevant ADRs, context artifacts, and repository instructions.
@@ -38,16 +37,18 @@ Create the destination directory only when a new artifact requires it.
Read the destination's `AGENTS.md` before any artifact write.
Follow the destination's filename, identifier, slug, frontmatter, and wikilink conventions.
If Wayfinder artifact reference is available, read it before writing.
The minimum Wayfinder ticket contract is:
The default implementation task artifact type is `implementation-task`.
The minimum implementation task contract is:
```markdown
---
status: open
parent: "[[<source-artifact-or-map>]]"
parent: "[[<source-artifact>]]"
blocked-by: []
claimed-by: null
claimed-at: null
tags:
- ticket/implementation
- task/implementation
---
# <task name>
@@ -57,9 +58,9 @@ tags:
<one precise implementation action sized to one agent session>
```
Use `ticket/task/human` instead of `ticket/implementation` when execution or validation requires human input before implementation can proceed.
Use `parent: null` when no earlier artifact directly caused the task.
Do not create claims.
Tickets start open and unclaimed.
Tasks start open and unclaimed.
Done when the destination and artifact conventions are known.
@@ -86,20 +87,20 @@ Each migration batch is sized by blast radius and is blocked by the expand slice
The contract slice removes the old form and is blocked by every migration batch.
When migration batches cannot stay green alone, keep the sequence but state the integration-branch constraint and add a final integrate-and-verify slice.
Done when every currently implementable slice has a title, type, blockers, delivered behavior, acceptance criteria, and any needed handoff notes.
Done when every currently implementable slice has a title, blockers, delivered behavior, acceptance criteria, and any needed handoff notes.
## 4. Classify ticket type
## 4. Confirm implementability
Use `ticket/implementation` when an agent can complete and verify the implementation slice without live human input.
Use `ticket/task/human` when execution or validation depends on the user before implementation can proceed.
Use implementation tasks when an agent can complete and verify the slice without live human input.
When execution or validation depends on the user before implementation can proceed, report the human dependency instead of writing an agent-grabbable task.
Examples include subjective UI judgment, physical device checks, unavailable credentials, external account approval, or behavior only the human can confirm.
Do not mark a ticket human merely because it is important or risky.
Make the required human involvement explicit in the ticket body.
Do not block a task merely because it is important or risky.
Make any required human involvement explicit in the proposed breakdown.
If slicing reveals a precise unresolved planning question, do not disguise it as an implementation ticket.
Report it and stop, unless the caller asks to create the appropriate Wayfinder research, prototype, or grill ticket.
If slicing reveals a precise unresolved planning question, do not disguise it as an implementation task.
Report it and stop, unless the caller asks for follow-up research, prototyping, or grilling.
Done when each proposed slice has the correct ticket type.
Done when each proposed slice is implementable by an agent or its human dependency is explicit.
## 5. Review before writing
@@ -108,7 +109,6 @@ For each slice show exactly this review shape:
```markdown
1. **Title**: <proposed task title>
**Type**: implementation or human task
**Blocked by**: <proposed blockers, or None>
**What it delivers**: <end-to-end behavior or implementation result>
**Acceptance criteria**:
@@ -122,14 +122,14 @@ In explicitly noninteractive mode, write the best breakdown and record any assum
Done when the proposed slices are approved or noninteractive assumptions are explicit.
## 6. Write ticket artifacts
## 6. Write task artifacts
Allocate filenames and identifiers according to the destination convention.
Create one Wayfinder ticket artifact per approved slice.
Create one implementation task artifact per approved slice.
Use the destination's wikilink style when referring to artifacts.
Never refer to a ticket by a bare identifier, filename, or slug in user-facing text.
Never refer to a task by a bare identifier, filename, or slug in user-facing text.
Each ticket body should use this shape:
Each task body should use this shape:
```markdown
# <task name>
@@ -155,24 +155,13 @@ Keep `## Implementation Notes` empty when no guidance earns its place.
Later implementing agents may append execution notes, verification results, and reasons for deliberately dropped criteria.
Avoid brittle file paths and code snippets unless a prototype or prior decision snippet encodes the decision more precisely than prose can.
Done when every approved slice has exactly one open, unclaimed Wayfinder ticket artifact.
## 7. Advance the Frontier
Re-read the map or parent artifact before editing shared state.
If there is a Wayfinder map, recompute its Frontier from ticket metadata.
A ticket belongs on the Frontier when it is open, every blocker is satisfied, and it has no claim.
The map's Frontier is the only map section that links to ticket artifacts.
Do not copy ticket details into the map.
If the destination uses identifier allocation and concurrent writes caused duplicate identifiers or filenames, preserve pre-existing artifacts, rename current outputs, update wikilinks, and advance the counter as needed.
Done when the ticket artifacts and map Frontier agree with current ticket metadata.
Done when every approved slice has exactly one open, unclaimed implementation task artifact.
## 8. Report
## 7. Report
Report the created ticket artifacts by title using the destination's link style.
Summarize the current Frontier.
Mention any assumptions, unresolved planning questions, or human-dependent validation tickets.
Report the created task artifacts by title using the destination's link style.
Mention any assumptions, unresolved planning questions, human-dependent validation, or immediately actionable unblocked tasks.
Done when the user can choose the next implementation task from the Frontier.
Done when the user can choose an implementation task.

154
skills/wayfinder/ARTIFACTS.md
View File

@@ -1,154 +0,0 @@
# Wayfinder artifacts
## Resolve the project
Resolve the artifact destination before naming files.
When the caller provides a destination directory, use it exactly.
Otherwise, default to `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>` when the AI artifacts vault is available, where `<project>` is the lowercase basename of the current working directory.
If that vault is unavailable, fall back to `./docs` in the current project.
Create the destination directory only when a new artifact requires it.
Read the destination's `AGENTS.md` before any artifact write.
Allocate identifiers only when the destination convention requires them.
## Names
Use an effort name that identifies one durable effort and is not reused for another map in the project.
Choose each filename from the destination's `AGENTS.md` and nearby artifact convention.
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.
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`, `task`, or `implementation`.
Do not use `ticket` as a filename artifact-type suffix.
## 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.
```markdown
---
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 or implementation outcome 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 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 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
A new ticket starts as:
```markdown
---
status: open
parent: "[[<map-or-surfacing-ticket>]]"
blocked-by: []
tags:
- ticket/<type>
---
# <ticket name>
## Question
<one precise question, prerequisite action, or implementation slice sized to one agent session>
```
Use one of these tags:
- `ticket/research`
- `ticket/prototype/afk`
- `ticket/prototype/hitl`
- `ticket/grill`
- `ticket/task/afk`
- `ticket/task/human`
- `ticket/implementation`
`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 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
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 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
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`, `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.
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 or filenames, preserve pre-existing artifacts, rename current outputs when required by the destination convention, update their links, and advance any counter required by that convention.
Recompute the Frontier only after returned artifacts and ticket states have been reconciled.

176
skills/wayfinder/SKILL.md
View File

@@ -1,176 +0,0 @@
---
name: wayfinder
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
---
# Wayfinder
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, 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.
## 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 a planning map and the time to hand off.
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 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.
## Refer by name
Refer to every map and ticket by its human-readable title using the destination's link style, never by a bare identifier, filename, or slug.
When the destination convention includes an artifact identifier, keep it inside the link without letting it stand in for the name.
## Ticket types
Every ticket is either **HITL**, worked through a live exchange with the human, or **AFK**, driven by the agent.
A HITL ticket only resolves through that exchange.
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`.
The called skill completes the Research ticket artifact in place.
- **Prototype** (AFK or HITL): Raise the fidelity of a logic, state-model, or UI decision through `prototype`.
Use AFK when the question has objective observable criteria the agent can test end to end.
Use HITL when the verdict depends on human judgment, taste, or UX feel.
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 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.
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
The map is deliberately incomplete.
Beyond its tickets lies the **fog of war**, where in-scope questions are visible but cannot yet be stated precisely because they depend on unresolved questions.
Resolving a ticket clears the fog ahead of it and graduates newly precise questions into tickets.
Use this test:
- Create a ticket when the question is precise now, even if it is blocked.
- Keep an entry under **Not yet specified** when the question cannot yet be phrased precisely.
Do not pre-slice fog into speculative tickets.
One fog entry may become several tickets or disappear as the frontier advances.
The destination fixes scope.
Work beyond it belongs under **Out of scope**, never under **Not yet specified**.
When an existing ticket proves to be beyond the destination, mark it out of scope and summarize the excluded work and reason in that section without an artifact link.
Do not record a scope boundary as a decision on the route.
## Select the mode
- A loose idea without a map uses **Chart the map**.
- An existing map uses **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 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
1. **Name the destination.**
Invoke `grill` to settle what this map is finding its way toward.
Done when the destination names the spec, decision, or change at the end of the effort and fixes its scope.
2. **Map the frontier breadth-first.**
Invoke `grill` again to fan out across the whole space without resolving any one branch in depth.
Surface every currently precise question, its blocking relationships, and the remaining fog.
If no fog remains and the whole 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 has exactly one home as 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 blocking relationships in a second pass according to [`ARTIFACTS.md`](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.
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.
Done when every dispatched Research ticket is resolved or records why it remains open.
5. **Stop.**
Stop without resolving a HITL ticket.
Done when charting has created and dispatched the visible route without consuming its human decision work.
## Work through the map
1. **Orient.**
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 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 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`, `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, 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 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 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.
Re-read shared artifacts before each write because other sessions may edit the effort concurrently.
Done when every newly visible question has exactly one home and the map agrees with all current ticket metadata.
6. **Complete, continue, or stop.**
When no unresolved tickets or fog remain, mark the map complete and stop for an explicit handoff instruction.
In a worker session, stop after one ticket is resolved and the frontier is advanced.
In an interactive or coordinating session, continue to another Frontier ticket only after reconciling the map and shared artifacts again.
Otherwise stop.
Done when the map records its current lifecycle state and no destination work has begun without permission.
## Coordinate workers
1. **Select dispatchable tickets.**
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.**
Re-read every shared artifact touched by returned workers.
Validate each ticket's claim, status, and canonical result.
Detect duplicate surfaced tickets or filenames, preserve pre-existing artifacts, and repair links according to [`ARTIFACTS.md`](ARTIFACTS.md).
Record whether a failed worker's claim remains, was reopened, or needs human recovery.
When Pi subagents supplied the worker results, call `subagent_clear` for each terminal child only after its findings have been reconciled into the artifacts or recovery record.
Done when all returned work is reconciled, every failed or missing worker result has an honest artifact state, and no reconciled terminal subagent remains in the visible work set.
5. **Advance the frontier.**
Recompute the Frontier after reconciliation, not before.
Mark the map `complete` only when no live ticket or fog remains.
Never use `resolved` as a map status.
Done when the map status, Frontier, and ticket metadata agree.