ai-artifacts/projects/skills/041-implement-skill-wayfinder-contract-research.md

status, parent, claimed-by, claimed-at, blocked-by, tags

status	parent	claimed-by	claimed-at	blocked-by	tags
resolved	038-implement-skill-map	019fbb66-80d0-7a01-8ac9-01255adfc7b2	2026-07-31T23:42:05-04:00		ticket/research

Implement skill Wayfinder contract research

Question

What Wayfinder artifact and lifecycle rules must a migrated implement skill follow when claiming, executing, resolving, and reporting Wayfinder task tickets?

Findings

Wayfinder plans by default and treats implementation as the edge of the map unless an effort explicitly permits execution in its Notes. A general implement skill can be the explicit destination-work executor, but it should not silently execute arbitrary Wayfinder planning tickets. It should restrict itself to Wayfinder task tickets that represent implementation handoff work or to maps whose Notes explicitly allow execution. Source: /home/alexion/.pi/agent/skills/wayfinder/SKILL.md.

Every Wayfinder ticket is either HITL or AFK and has one ticket tag. Task tickets use ticket/task/afk or ticket/task/human; Research, Prototype, and Grill tickets have separate resolution skills and are not implementation slices. A migrated implement skill can execute a ticket/task/human when it represents implementation work, but it must block and surface a precise human-input checkpoint when the task reaches the human-dependent step. It should stop with a plain explanation when asked to execute a non-task decision ticket. Sources: /home/alexion/.pi/agent/skills/wayfinder/ARTIFACTS.md, user correction in this session.

Ticket metadata is authoritative for lifecycle and readiness. A ticket is on the Frontier when status: open, every blocked-by artifact is satisfied, and it has no claim. A ticket blocker is satisfied when its status is resolved, and a non-ticket blocker is satisfied when the artifact exists. The migrated skill should verify these metadata conditions before claiming, rather than using legacy acceptance-checkbox completion as the readiness source. Source: /home/alexion/.pi/agent/skills/wayfinder/ARTIFACTS.md.

Claims must be persisted before work starts. Claiming means setting status: claimed, claimed-by to the current execution-session identifier, and claimed-at to the current timestamp. The acting agent should use PI_SESSION_ID when available. The migrated implement skill should claim exactly one actionable ticket before changing code, and should avoid consuming multiple tickets implicitly. Source: /home/alexion/.pi/agent/skills/wayfinder/ARTIFACTS.md.

Wayfinder tickets are self-resolving artifacts. The canonical result lives in the same ticket artifact, and a resolved implementation task should leave enough result detail for future readers without moving the result into the map. For implement, this implies appending implementation notes, verification results, commit hash, branch name, PR URL when available, deliberately dropped acceptance criteria, and any unaddressed review findings to the ticket artifact before setting status: resolved. Source: /home/alexion/.pi/agent/skills/wayfinder/ARTIFACTS.md.

The map is a route summary, not the store for ticket-level detail. Only the Frontier links to tickets or artifacts, and Decisions so far contains concise plain-language decisions for resolved Wayfinder decision tickets. Implementation task completion should update the map lifecycle and Frontier if the task belongs to a Wayfinder map, but the detailed implementation report belongs in the task ticket. Source: /home/alexion/.pi/agent/skills/wayfinder/ARTIFACTS.md.

Wayfinder requires shared artifacts to be re-read immediately before writes because concurrent sessions may be editing the same effort. A migrated implement skill should re-read the task ticket before claim, before closeout, and before any map Frontier repair. It should detect stale status, foreign claims, and changed blockers rather than overwriting them. Source: /home/alexion/.pi/agent/skills/wayfinder/ARTIFACTS.md.

Wayfinder's user-facing reference rule is by human-readable title in the destination's link style, never by bare identifier, filename, or slug. The migrated skill should refer to the task as a wikilink title when reporting, recording PR text, or writing related map updates, while file paths may still appear where tools need concrete paths. Sources: /home/alexion/.pi/agent/skills/wayfinder/SKILL.md, /home/alexion/.pi/agent/skills/wayfinder/ARTIFACTS.md.

The AI-artifacts vault convention requires project artifacts to be flat and named <NNN>-<scope-slug>[-<subject-slug>]-<artifact-type>.md, with identifiers allocated by incrementing the root .counter before creation. implement usually consumes an existing ticket rather than allocating new artifacts, but any follow-up task artifacts it creates must honor the destination's AGENTS.md and counter rules. Source: /home/alexion/Documents/ai-artifacts/AGENTS.md.

The existing slice skill map records the intended producer side of the same contract: implementation slices become Wayfinder task tickets with ## What to build, ## Acceptance criteria, and optional ## Implementation Notes, and the tickets are open and unclaimed until an implementer claims them. The migrated implement skill should be compatible with that produced format. Source: /home/alexion/Documents/ai-artifacts/projects/skills/031-slice-skill-map.md.

Conclusion

A Wayfinder-aware implement skill should execute exactly one actionable implementation task ticket at a time, claim it in metadata before code changes, respect blocked-by and existing claims, record implementation results in the same ticket artifact, transition it to resolved, and repair the owning map's Frontier without storing implementation detail in the map. It may execute HITL task tickets when they are implementation work, but must pause at the point human input is required and record the blocked state plainly. It should not execute research, prototype, grill, blocked, claimed, or out-of-scope tickets as normal implementation work.