feat(skills): add isolated worker workflow guidance

skills/implement/SKILL.md

@@ -11,6 +11,10 @@ This skill defines execution protocol rather than deciding what work the agent i
 When selected work has a Wayfinder task 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.
+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.
+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.
@@ -53,7 +57,9 @@ Done when the checkout, branch, dirty state, and reachable prerequisites are saf
 ## 3. Implement the work
 
 Use `test-driven-development` as a strong default when behavior can usefully be specified and tested before implementation.
+Load `test-driven-development` before deciding whether it applies.
 Skip it only when the work is mechanical, documentation-only, exploratory, or when test-first would not add value.
+When skipping it, state the reason before implementation.
 Skipping test-driven development is an agent judgment, not an omission.
 
 Build the selected work in the assigned checkout.
@@ -69,7 +75,7 @@ Done when the selected work is implemented as working code and locally verified
 
 ## 4. Review the final intended handoff state
 
-Run `review` before reporting final handoff or resolving a Wayfinder task.
+Load and run `review` before reporting final handoff or resolving a Wayfinder task.
 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.

skills/review/SKILL.md

@@ -29,9 +29,11 @@ Done when the chosen change set is explicit and reviewers have enough input to j
 
 ## 2. Run dimension reviews
 
-Run independent dimension reviewers when the runtime supports subagents or isolated workers.
+Run independent dimension reviewers through whatever real context boundary the current harness provides.
+A separate agent, worker, subprocess, or documented headless session is sufficient when each reviewer can inspect its dimension without seeing the parent review's intermediate conclusions.
 Use one reviewer per dimension when practical.
-Fall back to a single-agent review when independent workers are unavailable, but preserve separate report sections.
+If no real context boundary is available, state that limitation before reviewing.
+Proceed in-process only as an explicitly degraded fallback, and preserve separate report sections.
 
 Use these reviewer files:
 

skills/subagents/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: subagents
+description: Delegate isolated work through Pi subagent tools. Use when a workflow needs an independent worker, fresh context, parallel reviewers, or hidden role separation.
+disable-model-invocation: true
+---
+
+# subagents
+
+## 1. Confirm support
+
+Prefer tool calls when the current runtime exposes them.
+The supported tool names are `subagent_spawn`, `subagent_batch`, `subagent_list`, `subagent_status`, `subagent_result`, and `subagent_cancel`.
+
+If these tools are unavailable, do not pretend that an in-process role switch is a subagent.
+State that Pi subagent tools are unavailable in the current runtime.
+Do not perform the delegated subagent work in-process unless the caller explicitly permits a degraded fallback.
+
+Done when the run has either a supported subagent tool path or a caller-approved degraded mode.
+
+## 2. Prepare a bounded prompt
+
+Give each subagent a self-contained prompt.
+Include the role, task, repository path, relevant files or artifacts, constraints, and expected output shape.
+Do not expose private planning state that the workflow is trying to isolate.
+For test-driven development, send one behavior at a time rather than a backlog.
+For review, send one review dimension at a time unless batching independent dimensions.
+
+Use `context: "independent"` for a fresh worker by default.
+Use `context: "fork"` only when the child intentionally needs the parent transcript as starting context.
+Choose named agents only when the project has configured them.
+Do not invent named agents as part of the delegation.
+
+Done when the prompt is narrow enough that the subagent can complete without sharing hidden state or requiring follow-up orchestration.
+
+## 3. Spawn and track workers
+
+Use `subagent_spawn` for one worker.
+Use `subagent_batch` when several independent workers can run in parallel.
+Both spawn tools return before the child work is complete.
+Record accepted child ids and per-entry failures.
+Use `subagent_list` or `subagent_status` to track lifecycle when needed.
+Use `subagent_result` to retrieve completion output.
+Use `subagent_cancel` for stale or no-longer-needed workers.
+
+Do not claim the delegated work is complete until every required child result is available or a failed child has an explicit disposition.
+Treat `queued`, `starting`, `running`, and `settling` as incomplete states.
+Treat `failed`, `cancelled`, `timed_out`, and `orphaned` as failures unless the caller explicitly accepts the missing result.
+
+Done when every required worker result has been collected or every missing result has a stated disposition.
+
+## 4. Integrate results
+
+Use subagent output as evidence, not as an unquestioned command.
+Preserve which child produced each material finding.
+When subagents disagree, report the disagreement rather than averaging it away.
+When a subagent result changes implementation direction, verify the relevant facts in the parent context before editing code.
+
+Done when the parent has integrated child results into the caller workflow with provenance and limitations visible.

skills/test-driven-development/SKILL.md

@@ -15,8 +15,10 @@ The implementation agent changes production code and drives the loop.
 The test writer writes and edits tests.
 Tests are always written by someone other than the agent doing implementation.
 
-Use an independent test writer when the runtime can spawn an independent worker.
+Launch an independent test writer through whatever real context boundary the current harness provides.
-If the runtime truly cannot spawn an independent worker, state that limitation before writing tests and preserve role separation in-process as much as possible.
+A separate agent, worker, subprocess, or documented headless session is sufficient when it cannot see the implementation agent's private backlog.
+If no real context boundary is available, state that limitation before writing tests.
+Proceed in-process only as an explicitly degraded fallback, and preserve role separation as much as possible.
 Do not silently skip the independent-test-writer requirement.
 
 The implementation agent may keep a private behavior backlog.

skills/wayfinder/SKILL.md

@@ -17,11 +17,14 @@ It is the single source of truth for how maps, tickets, claims, blocking, resolu
 
 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 the map and the time to hand off.
+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 AFK Task tickets may deliver implementation slices.
+
 The destination varies by effort and shapes every ticket.
-It may be a spec to hand off, a decision to lock before planning, or a change whose route must be understood before implementation.
+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
 
@@ -42,11 +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 that must happen before a decision can be made.
+- **Task** (AFK or HITL): Perform prerequisite work or implementation 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.
 
-A Task earns its place by unblocking a decision, not by delivering part of the destination.
-
 ## Fog of war
 
 The map is deliberately incomplete.
@@ -70,9 +73,13 @@ 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 delegated worker resolves exactly one claimed ticket and stops.
+A worker session 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.
+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.
 Do not auto-consume HITL tickets without user participation.
 
 ## Chart the map
@@ -104,10 +111,11 @@ Do not auto-consume HITL tickets without user participation.
    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.
    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.
-   Done when exactly one unblocked ticket records this session's claim with `status: claimed`.
+   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.
    Perform a Task through the capability or human checklist it requires.
@@ -124,7 +132,35 @@ Do not auto-consume HITL tickets without user participation.
    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 delegated worker session, stop after one ticket is resolved and the frontier is advanced.
+   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.
+   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.
+   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.
+   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 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.
+   Done when all returned work is reconciled and every failed or missing worker result has an honest artifact state.
+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.