---
status: complete
tags:
  - wayfinder/map
---

# Implement workflow

## Destination

Create an implementation-ready plan for migrating the packaged implementation workflow to Wayfinder-aware skills in this skills repository.
The route ends when the `implement`, `test-driven-development`, and review skill contracts, dependencies, artifact lifecycle, git and PR handling, and migration scope are decided enough to hand off implementation.

## Notes

The workflow includes packaged `implement`, `test-driven-development`, and review skills.
The review skill is named `review`.
The old Claude Code skill sources live under `/home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/implement/`, `/home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/test-driven-development/`, and `/home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/review-uncommitted/`.
The new packaged skill sources, if implemented later, would live under `skills/implement/`, `skills/test-driven-development/`, and `skills/review/` in this repository.
Runtime enablement in dotfiles or another consumer repository is out of scope unless a later decision explicitly broadens the destination.
Wayfinder-aware implementation should work with Wayfinder task tickets and preserve useful execution, review, commit, and PR mechanics from the old workflow only where they still fit the artifact contract.
Research comes before HITL decisions.

## Frontier

None.

## Decisions so far

The migration scope includes the complete implementation workflow: packaged `implement`, packaged `test-driven-development`, and packaged `review`.
Preserve explicit task selection, blocker safety, conservative git branching from `main`, no automatic stashing or destructive resets, TDD where appropriate, regular verification, specific staging, pre-commit review, deviation notes, one commit per task, and useful PR reporting, but adapt task identity, blocker readiness, branch naming, spec source, task closeout, PR references, and lifecycle state from legacy `.claude/tasks` conventions to Wayfinder task-ticket artifacts.
Execute exactly one actionable implementation task ticket per session 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.
HITL task tickets can be implemented until they reach the point requiring human input, where the skill must pause and surface the precise human checkpoint.
Create dedicated follow-up research for Matt Pocock's `implement`, `to-tickets`, `tdd`, `code-review`, and `wayfinder` skills, but not for handoff skills unless the destination expands to session handoff automation.
Use Matt Pocock's `implement` as a simplicity reference, but keep stricter local handling for Wayfinder claiming, branch setup, artifact closeout, and PR or handoff reporting.
Preserve Matt Pocock's tracer-bullet, blocker, frontier, and wide-refactor concepts from `to-tickets`, but reject tracker labels and issue-specific publication mechanics in favor of Wayfinder task metadata.
Preserve public-seam, anti-tautology, one-test-at-a-time TDD discipline, while leaving the timing and authority of refactoring as a human decision.
Use the Wayfinder task as the primary review spec source, preserve separate Standards and Spec axes plus the smell baseline, and decide whether to retain the local Risk axis and pre-commit review timing.
Adapt Matt Pocock's Wayfinder planning-versus-execution boundary, HITL protection, and frontier/claim concepts, while rejecting tracker-specific labels, child-issue assumptions, assignee claims, issue IDs, and native blocking mechanics.
Learn from Kun Chen's `no-mistakes` that preventing AI slop requires a fixed ordered gate, rich intent, isolated validation, structured findings, bounded auto-fix, human escalation for judgment calls, trusted validation configuration, and CI-backed proof before public handoff.
Worktree isolation is expected to be essential for parallel Wayfinder implementation.
Treehouse leasing is the strongest candidate when available: acquire an isolated reusable worktree, create or check out the task branch inside it, record lease identity in the ticket, avoid destructive cleanup when dirty, and release with identity checks after successful handoff.
Keep Herdr worktree and pane orchestration external to the core skill unless the destination expands, while remaining compatible with Herdr-managed worktrees, setup hooks, and `.worktreeinclude`-style ignored-file copying.
Do not package `codebase-design` as part of this workflow; fold the small amount of useful seam and public-interface testing guidance into `test-driven-development` and `review` instead.
Treat worktree orchestration, dirty-repo guards, lease cleanup, visible Herdr panes, and multi-agent execution as Pi extension or external-tool integrations outside this skill migration.
The `implement` skill defines execution protocol rather than policing admissible work sources: when selected work has a Wayfinder task artifact it follows Wayfinder claim, blocker, result, resolution, and Frontier protocol, and when no artifact exists the implementation artifact is simply the working code plus normal review, commit, and handoff output.
The `implement` skill is worktree-compatible rather than a worktree orchestrator: it assumes the session already has the right checkout, checks dirty state, never auto-stashes, uses or creates a non-default branch from an updated default branch when needed, follows repository, user, or orchestrator branch naming, preserves the old blocker-reachability guardrail, and only uses integration-branch or wide-refactor branch strategy when the plan explicitly calls for that exception.
The review skill is named `review`; it selects a context-appropriate change set, states that scope, emits a structured report rather than a gate artifact or pass/fail verdict, covers Risk, Standards, Intent, Evidence, and Documentation when applicable, may run targeted checks, remains report-only, uses independent dimension reviewers with single-agent fallback, keeps reviewer prompts as self-contained files under the skill directory, and preserves ambiguity where agent judgment is useful.
The `test-driven-development` skill folds in minimal public-interface and seam guidance instead of depending on packaged `codebase-design`, requires tests to be written by someone other than the implementation agent with an explicit fallback only when independent workers are unavailable, isolates the implementation agent's behavior backlog from the test writer, runs red-green one behavior at a time, requires independent expected-value sources, forbids implementation agents from editing test-writer-authored tests, and preserves the old local refactor-after-green behavior.
The code is the implementation artifact; Wayfinder task closeout records durable coordination facts only, uses `status` as lifecycle authority, may update acceptance-criterion checkboxes as useful detail, keeps Implementation Notes concise, leaves partial or ambiguous outcome disposition to agent judgment, and must keep lifecycle recording honest.
No extras are in scope beyond the packaged `implement`, `test-driven-development`, and `review` skills: do not add legacy `.claude/tasks` compatibility shims, dedicated worktree-extension documentation, Herdr integration, or Treehouse integration.
The `implement` skill uses `test-driven-development` as a strong default when behavior can usefully be specified and tested before implementation, consumes it as process discipline rather than a report artifact, must run `review` before final handoff or Wayfinder task resolution, lets the agent choose review timing as long as review covers the final intended handoff state, fixes or explicitly accepts blocking review findings, uses judgment for non-blocking findings, and prescribes no other supporting skill invocations.

## Not yet specified

None.

## Out of scope

Implementing the migrated skills is outside this map until the route is complete and the user explicitly asks for destination work.
Building a Pi extension for worktree orchestration, dirty-repo guards, lease cleanup, visible Herdr panes, or multi-agent execution is outside this skill migration.
The skill workflow should remain compatible with such an extension.
