Compare commits

..

3 Commits

Author SHA1 Message Date
99df169fbd Relax Wayfinder session ticket limit 2026-07-31 20:46:14 -04:00
8035e0e436 Allow AFK prototype tickets 2026-07-31 20:43:18 -04:00
012a4bfd1e Unify Wayfinder ticket artifacts 2026-07-31 20:38:27 -04:00
6 changed files with 54 additions and 32 deletions

View File

@@ -76,14 +76,17 @@ If the host project has no task runner, put the command at the top of the protot
Done when a fresh user can launch the prototype with one documented command.
### 6. Hand it over
### 6. Evaluate it
Give the user the run command.
In HITL mode, give the user the run command.
They drive it themselves.
The interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" because those expose bugs in the idea.
Add actions when the feedback needs them.
Done when the user can exercise the model and the prototype exposes every state transition needed to reach a verdict.
In AFK mode, run the command yourself and drive the hard cases that answer the stated question.
Record the observations that support the verdict.
Done when the evaluator can exercise the model and the prototype exposes every state transition needed to reach a verdict.
## Production mapping

View File

@@ -7,6 +7,9 @@ description: Build a throwaway prototype to answer a design question. Use when t
A prototype is **throwaway code that answers one question**.
The question decides the branch.
The interaction mode decides who reaches the verdict.
Use AFK mode when the question has objective observable criteria the agent can test end to end.
Use HITL mode when the verdict depends on human judgment, taste, or UX feel.
## 1. Pick a branch
@@ -39,11 +42,13 @@ Done when exactly one branch and one design question govern the prototype.
## 2. Build and reach a verdict
Follow the selected branch through its handover step and iterate on the prototype in response to the user's feedback.
Follow the selected branch through its evaluation step.
In HITL mode, hand the prototype to the user and iterate in response to their feedback.
In AFK mode, run the prototype yourself and evaluate the objective observations against the question.
Do not treat a runnable prototype as the result.
The result is the verdict that answers the design question.
Done when the user has reached an explicit verdict or stated that the prototype did not resolve the question.
Done when the verdict is explicit, or when the prototype establishes that it did not resolve the question.
## 3. Capture the primary source
@@ -61,11 +66,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.
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.
Create only the Prototype artifact and leave the parent artifact unchanged.
When the caller provides an existing ticket 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:
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.
- Logic evidence uses useful code snippets and, where needed, a short interaction transcript.

View File

@@ -99,12 +99,15 @@ Put the switcher in a single shared component so both sub-shapes can reuse it. L
Done when mouse and keyboard controls cycle through every shareable variant without intercepting text-editing keys, and the switcher cannot render in production.
### 5. Hand it over
### 5. Evaluate it
Surface the URL and the `?variant=` keys.
In HITL mode, surface the URL and the `?variant=` keys.
The user flips through the variants and may combine elements rather than choosing one unchanged.
Done when the user can compare every variant in its host context and the prototype exposes enough contrast to reach a verdict.
In AFK mode, open the URL yourself, compare every variant against the stated objective criteria, and record the observations that support the verdict.
Use HITL instead when the decision depends on taste, product judgment, or UX feel.
Done when the evaluator can compare every variant in its host context and the prototype exposes enough contrast to reach a verdict.
## Production mapping

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.
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.
Create only the Research artifact and leave the parent artifact unchanged.
When the caller provides an existing ticket 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 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
@@ -40,6 +39,7 @@ Done when the question is answered as far as primary evidence permits and every
## 3. Write the Research artifact
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.
Do not create a source dump or research log.

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.
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
@@ -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.
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
@@ -95,7 +97,8 @@ tags:
Use one of these tags:
- `ticket/research`
- `ticket/prototype`
- `ticket/prototype/afk`
- `ticket/prototype/hitl`
- `ticket/grill`
- `ticket/task/afk`
- `ticket/task/human`
@@ -108,7 +111,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.
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 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.
## Claims and status
@@ -130,12 +133,12 @@ An out-of-scope ticket is closed, while **Out of scope** states the excluded wor
## 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 the result in a child artifact whose `parent` points to the ticket.
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 artifact destination, the filename chosen from that destination's convention, and the ticket link that the result must use as its `parent`.
The called skill creates the result artifact but does not edit the ticket or map.
The coordinating Wayfinder agent validates the returned artifact, marks the ticket resolved, and updates the map.
When invoking `research` or `prototype`, 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.

View File

@@ -35,9 +35,11 @@ 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 creates a Research artifact and Wayfinder integrates it.
- **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 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 must happen before a decision can be made.
@@ -69,7 +71,9 @@ 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**.
Never resolve more than one non-Research ticket in a session.
A delegated worker resolves exactly one claimed ticket and stops.
An interactive or coordinating Wayfinder session may resolve multiple tickets sequentially, but 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
@@ -86,9 +90,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.
4. **Dispatch Research.**
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.
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.**
Stop without resolving a HITL ticket.
Done when charting has created and dispatched the visible route without consuming its human decision work.
@@ -110,15 +114,17 @@ Never resolve more than one non-Research ticket in a session.
Load related artifacts only when needed.
Done when the question has a resolution or the prerequisite Task is complete.
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).
Do not link or identify the resolved ticket or its result artifacts from the map.
Done when the resolution lives in exactly one canonical place and the map states only the resulting decision.
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 from the map.
Done when the resolution lives in the ticket artifact and the map states only the resulting decision.
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 or stop.**
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 delegated 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.