@jmfederico/pi-web 1.202610.1 → 1.202610.2

package/dist/pi-packages/relays/skills/relay-runner/SKILL.md

@@ -1,253 +1,74 @@
 ---
 name: relay-runner
-description: "Opinionated full-lifecycle software-delivery profile for Relay chains in Git repositories. Load when preparing or running every leg of a Relay created by /relay or /relay-worktree, whenever a preparation or handoff prompt names relay-runner, or when an active Relay operations record declares this profile. Governs scope, adaptive leg sizing, checkpoints, verification, commits, review/remediation, delivery, and handoff. Do not load for generic Relay questions or Relays that declare another operational profile."
+description: "Prepare and run Relay legs in Pi: keep the goal, baton, and log durable, then hand off to one fresh session or stop visibly. Use with relay for /relay, /relay-worktree, or a handoff naming relay-runner. Supplies continuity and a bounded fresh-context final review without prescribing the development route."
 ---
 
 # Relay runner
 
-Use this skill as the opinionated software-delivery profile layered on the project-neutral `relay` method. It assumes a Git repository and optimizes for small, durable, independently reviewable progress from initial dispatch through delivery.
+This skill binds the `relay` method to Pi sessions and a small file packet. It supplies continuity and one completion gate: a fresh-context final review. The development route remains adaptive. Each agent discovers applicable project instructions and skills through the repository and harness; do not copy them into the packet or preselect them for future legs.
 
-This profile binds the base `relay` method's tool-agnostic principle, durable-state roles, context containment, and invariants to Pi's session tools and an opinionated Git/software-delivery workflow. Dispatch and handoff prompts are responsible for selecting both skills before a runner begins; skill bodies do not bootstrap other skills.
+## Packet
 
-## Profile contract
+Use `.pi-web/relays/<name>/` in the working checkout unless the user selects another location inside the target workspace. Start with three files:
 
-For a Relay using this profile:
+- **`charter.md` — goal.** The agreed outcome and recognizable finish line, relay-specific scope boundaries and clarifications, and any explicit human requirements. Reference an existing specification when useful. Do not add project rules, implementation plans, or generic quality or delivery procedures; include such details only when the human explicitly asks.
+- **`status.md` — baton.** State (`Draft — awaiting approval; not dispatched`, `Active`, `Complete`, or `Needs help`), last completed leg and next leg number, working location, current progress, remaining gaps to the goal, relevant checks, current review state, targeted pointers, and blockers. Include only what is useful now. Avoid suggesting the next slice; record remaining gaps and concrete dependencies instead.
+- **`log.md` — history.** Append a short entry per leg: what changed or was learned, important decisions and why, artifact or commit references, checks and actual results, and the next leg or stop. Record human approval and scope changes here too.
 
-- Have the preparation prompt select `relay-runner` before drafting the packet. Record it immediately in draft `operations.md` and retain it as required for every active leg, including implementation, review, remediation, and delivery.
-- Name both `relay` and `relay-runner` in every handoff prompt. Fresh sessions cannot inherit a prior runner's loaded skills.
-- Keep every Relay handoff on the current runner's model by omitting the `model` argument, unless instructed to use a specific model or to choose an appropriate one. Record any Relay-wide model instruction in `operations.md` so it remains available to later runners.
-- Treat the charter as destination and scope edges, `operations.md` as this profile's repository and execution bindings, `status.md` as current position and next work, and repository instructions as the quality and implementation authority.
-- Follow canonical repository policy when it conflicts with a profile default. Record a material operational adaptation in `operations.md`, not the charter. Stop for human intervention when reconciling the conflict would change the finish line or an edge, weaken a protected invariant, or require a product or business decision.
+Charter = agreement; status = position; decisions = durable reasoning; log = history. Keep revisions in the log, not a separate revisions document; no decision template is required. Status, decisions, and the log cannot silently change the agreement. Keep relay-specific decisions durable without adding documents merely to satisfy a template. The packet is not a second home for project policy or this skill's instructions.
 
-This profile is intentionally strong. A project that wants another way of working should use the base `relay` skill with a different profile rather than quietly diluting this one leg by leg.
+Add **`decisions.md` only when useful**: a compact, living record of consequential decisions and their reasons, including rejected approaches or review concerns worth remembering. Keep current conclusions there and record revisions in the log. Link it from status and consult relevant entries rather than duplicating the reasoning in the baton. It is not a plan, task list, or another home for project rules. Human changes to the goal or scope still belong in the charter. Do not create an empty register or impose a decision template.
 
-## Pi execution and packet
+## Preparation and dispatch
 
-`spawn_session` is fire-and-forget: the current runner does not receive the successor's output and cannot steer it. The packet is the only thread across the chain. Complete all work and durable-state updates before handoff, then call `spawn_session` at most once as the leg's final operational action. After it returns, provide only a user-facing handoff summary; do not use more tools, mutate state, perform more Relay work, or try to steer the successor. Do not use a tracked subsession for the Relay handoff; tracked subsessions are allowed only as bounded helpers inside a leg when this profile explicitly permits them.
+The preparation prompt owns discussion and approval. Drafting is allowed before approval; `dispatch_relay` is not. After the human reviews the goal and boundaries, require an explicit **Approve and dispatch** response. If the approved goal, scope, or working target changes materially, obtain fresh approval.
 
-Default the packet root to `.pi-web/relays/<name>/` unless the preparer selects another location. During preflight, create a reviewable draft packet in the checkout where the preparation session is running and mark it not dispatched. For fresh-worktree mode, move the complete packet into the target worktree before handoff and remove the stale drafting copy. Use the base method's three durable-state files plus one profile-owned operational record:
+Use the current checkout for `/relay` unless the user chooses another. For `/relay-worktree`, create a fresh branch and worktree after approval, following project conventions; use current HEAD as the starting point unless another base is agreed. Ask about a material target ambiguity rather than guessing. Move the draft packet into the target checkout before dispatch, update its location, and remove the stale drafting copy.
 
-- **`charter.md` — goal and edges.** Record Relay identity, the plain-language goal and observable finish line, minimum outcome acceptance, in-scope boundaries, explicit non-goals, material assumptions or human decisions. Keep it free of implementation plans, technical route definitions, quality bars, verification commands, review heuristics, and copied project guidance. Include a technical contract only when the user made that contract part of the desired outcome or a necessary scope edge. Changing the goal or an edge requires explicit human agreement, a charter update, and a log entry.
-- **`operations.md` — runner bindings.** Record the packet and profile identity, canonical project instruction pointers, working location and Git facts, verification commands, packet isolation, commit and checkpoint policy, review budget and delivery mechanism, intervention signal, and any explicit profile adaptation. These are operating facts and policies, not product scope; maintain them without rewriting the charter.
-- **`status.md` — compact baton.** Record current position, last completed leg, next leg identifier, current or next task, targeted context pointers, progress-documentation expectations, blockers, and active transition or review-decision pointers. Status selects the route; it cannot redefine the charter. Compress history out of it.
-- **`log.md` — append-only history.** Append one concise entry per leg covering work and decisions, durable artifacts, verification, packet updates, and handoff or stop. Read only targeted entries referenced by charter, operations, or status; never read it end-to-end defensively.
+Record the actual checkout and, in Git, branch and starting commit in status. Keep packet files out of delivery commits using an existing ignore rule or a local Git exclusion. Leave unrelated existing work untouched. Bootstrap the target as needed under project conventions; setup does not automatically require a separate leg.
 
-Do not add `plan.md`, a roadmap, or generic planning/design documents to the packet. The only optional packet files in this profile are a targeted `transition.md` while a transitional checkpoint is active and a targeted `review-decisions.md` while unresolved whole-work findings require continuity. Status must link each active optional file; when that need ends, record its conclusion in the log and remove both the pointer and optional file. Put any task- or project-specific durable artifact in its canonical project or delivery location and link it through a targeted status pointer instead of expanding the packet format. If status is insufficient, repair it with targeted inspection. Intervene rather than reconstructing broad history or guessing what “done” means.
+Record approval in status/log, mark status `Active`, and seed leg 1. The first runner chooses its own slice; preparation need not prescribe one. Dispatch with the same handoff mechanics used by later legs.
 
-Authority follows role, not recency: charter owns destination and edges, operations owns this profile's execution bindings, status owns current position and next work, and log preserves history. Canonical repository instructions own project quality and implementation policy. None of the operational surfaces can override the charter.
+## Run a leg
 
-## Goal and scope
+1. Read the charter and status, then inspect relevant project guidance and work. Consult only the history or supporting material needed to understand the current state. Repair small record gaps with targeted inspection; ask for help if the goal or ownership is unclear.
+2. Compare reality with the finish line and completion requirements, including the final review below. If all are satisfied, record completion and stop. Otherwise choose one useful, context-sized slice that closes a remaining gap. Briefly state in the session which slice you chose and how it advances the goal.
+3. Do the work and the checks appropriate to it under project conventions. Record failed, skipped, or incomplete checks honestly.
+4. Make the result durable before handoff. In Git, commit the leg's changes when project policy and human instructions permit, without including unrelated changes or the packet. Otherwise record the exact saved work and why it is uncommitted. Finish any helpers before handing off.
+5. Refresh the compact status and append the log entry. Record progress against the goal, important evidence and decisions, remaining gaps, and any limitations the successor needs to know. Then complete, ask for help, or hand off once.
 
-Under this profile, Relay completion means the chartered outcome has been reached and every completion gate required by `operations.md`—including whole-work review, approval, and delivery—has completed. Keep those operating gates in `operations.md` rather than adding them to the charter.
+Other reviews, delivery steps, and gates apply only when the human or project requires them. Keep this skill's review procedure here, not copied into the packet.
 
-Translate source material into a plain-language, observable finish line without adding outcomes. Understanding intent does not authorize extra behavior. Treat the current repository as the baseline and include only:
+## Final review
 
-- work explicitly requested;
-- work necessary to reach the finish line; and
-- directly coupled work needed to prevent this Relay's changes from causing regressions.
+When a leg finishes substantive work and believes implementation is done, record that final review is pending and hand off to a fresh leg. A fresh runner finding implementation complete with review pending performs the review instead of passing it on again. Leave substantive corrections to another leg so the review stays independent.
 
-Record only the minimum observable outcome acceptance and scope edges needed to recognize completion: what is in, what is explicitly out, any directly affected behavior the goal must preserve, and material assumptions or decisions. Prefer product language. Do not add technical definitions, quality criteria, speculative failure cases, or implementation constraints merely to make the charter look complete; project instructions govern quality directly. Leave optional cleanup, hardening, refactoring, and features outside the Relay unless the user approves them.
+Review the whole relay result, not just the last slice, against the charter and applicable project guidance. Approve when no concrete, evidence-backed in-scope blocker remains. Optional improvements, speculative concerns, and unrelated pre-existing shortcomings do not block completion. Record consequential finding dispositions in `decisions.md` when useful.
 
-## Adaptive legs without an upfront plan
+Allow **at most three review attempts total**: the initial review and up to two post-correction reviews, not three mandatory passes. Keep the attempt count, latest result, and reviewed work reference in status; put evidence and findings in the log or link to decisions. Subsequent attempts happen only after concrete corrections and focus on those corrections and changed evidence, carrying supported prior decisions forward rather than restarting an expanding audit.
 
-Relay intentionally does not predict the chain. Before dispatch, establish the destination and edges and select only the first bounded leg. Do not create work packages, an exhaustive stage sequence, a file/layer map, or a promised leg count. Future runners choose the next slice from current reality and the finish line.
+If the third attempt still has blockers, or a required further review would exceed the budget, mark `Needs help`, record what remains, and stop without dispatching another review or correction leg. A valid approval satisfies the gate; a new context or packet-only update does not reopen it. Material changes to the reviewed result require re-review within the same budget.
 
-Expected files, subsystems, dependencies, architecture, and sequencing are route assumptions. Keep only what the current or next leg needs in status or a targeted temporary artifact; do not turn route assumptions into stable agreement.
+## Stop or hand off
 
-A leg is one context-contained, reviewable slice that advances the finish line. Development legs implement and verify by default: optimize for the smallest useful behaviour, not the smallest independently testable artifact. A functional checkpoint makes an observable charter outcome available and verifies it through the relevant application boundary. A tested but unused module is a prerequisite, not a functional outcome. Setup, required verification, review and delivery remain legitimate lifecycle legs.
+Mark `Complete` and report the result and evidence when no required work remains and final review has passed for the current result. Do not spawn a successor to search for extra work.
 
-Slice by supported cases across the necessary layers. When a journey is too large, choose a narrower case or a safe partial capability with explicit limitations, keeping the full charter outstanding. Keep directly coupled implementation, checks, contracts, generated outputs, documentation and integration together.
+Mark `Needs help` when a decision, permission, environment problem, or lack of progress prevents responsible continuation. Record the concrete blocker, attempts and evidence, and the smallest question or action needed from the human. Surface it clearly in the user-facing response; use `ask_user` when an answer is needed. Do not hand a human-dependent blocker to another context hoping it will disappear.
 
-Before substantial work, state the leg's:
+Before continuing, check that concrete required work remains, including any pending final review; leave slice selection to the successor.
 
-- observable outcome and application boundary;
-- bounded change surface and coupled verification;
-- remaining connection to usable behaviour, if any; and
-- checkpoint type: functional, necessary prerequisite or profile-authorized transitional.
+For handoff, finish work and all packet writes first. The charter supplies the goal and saved `status.md` is the actual baton: save progress, remaining gaps, decisions, checks and blockers there, with targeted pointers to supporting records as needed. Do not put missing continuity into a separate handover prompt.
 
-An unconnected prerequisite must name the behaviour it enables and why a connected slice cannot reasonably fit. Its successor prioritizes that connection. Before adding another prerequisite-only leg, reassess the slice and simplify the route; continue only when a concrete dependency still prevents connection.
+Call the dedicated `dispatch_relay` tool at most once with the saved directory as `packet`, the next leg identity as `leg`, and the target checkout as `cwd`. A relative `packet` resolves inside that `cwd`; custom packet locations must also stay inside the target workspace. Pass `leg` as a string: the next leg number written as `"2"`, or an explicitly chosen identifier of 1–32 letters, digits, dots, underscores or hyphens, starting with a letter or digit. Non-string values are rejected rather than converted. For example, substitute the actual paths and next leg:
 
-Routine reading, design, sizing and test investigation belong inside implementation. A research-only leg requires a specific unanswered question blocking responsible implementation: record the blocked behaviour, why available evidence is insufficient and the result needed to proceed. Answer that question and hand off to implementation; intervene if it remains unresolved. Size or complexity alone calls for a smaller implementation slice.
-
-Choose the simplest design satisfying the charter, canonical project rules and concrete risks introduced by the change. Justify additional safeguards against those obligations; keep speculative recovery systems and future-use abstractions outside the slice. Preserve safety when narrowing behaviour.
-
-Persist only conclusions useful to the next runner. Keep leg history in the packet log and project documentation focused on current behaviour and contracts.
-
-If a leg grows beyond its context-contained slice, stop broadening before context exhaustion. Finish or revert to a coherent functional or justified prerequisite checkpoint, or use an already authorized transition. Record the next bounded slice. Do not promise a fixed total leg count.
-
-When status does not name the next task, choose the smallest coherent slice that advances the critical path or unblocks an agreed outcome. Do not invent cleanup or speculative follow-up merely to fill a leg.
-
-### Bounded transitional checkpoints
-
-Use a transitional checkpoint only when a functional split would make the leg unreasonably large or require disposable compatibility work, and repository policy permits it. Before making the repository non-functioning, record a breakage budget containing:
-
-- expected affected surfaces and failure classes;
-- the last known functional commit;
-- a recovery action if handoff fails;
-- a named restoration milestone; and
-- safety constraints.
-
-Keep the active summary in `status.md`. Put larger details in `transition.md`, link it from status, and preserve the pointer until restoration.
-
-A transitional leg may leave only failures inside that declared budget. The incomplete state must intentionally advance an agreed outcome, complete a coherent transformation step, and receive every focused check meaningful for that step. Every following leg while the transition is active must continue or restore it; do not start unrelated work. Never authorize a transition that creates an unsafe security, authorization, data-integrity, or irreversible external-effect state.
-
-Treat a failure outside the budget as unexpected; resolve it or intervene rather than relabeling it after the fact. Make the checkpoint durable under the operations record's commit policy and record exact verification, recovery, and next work before handoff. If the Relay must stop before restoration, execute the recovery action unless `operations.md` explicitly permits the isolated state to remain safely available for human recovery. Do not start whole-work review or delivery until the repository is functional and final verification requirements can pass.
-
-## Support preflight and dispatch an approved Relay
-
-### Discover only what the packet needs
-
-Read `AGENTS.md` and other canonical agent or contributor instructions, then follow only the references needed to establish:
-
-- applicable project skills or quality standards every runner must use;
-- focused and full verification commands, including manual checks when automation is absent;
-- integration base ref and immutable base commit;
-- review range and allowable pre-existing working-tree state;
-- commit conventions;
-- fresh-worktree bootstrap requirements, if applicable;
-- review and delivery mechanism, plus an achievable fallback when remote or review tooling is unavailable; and
-- packet isolation from delivery commits and the reviewed diff.
-
-Point `operations.md` at canonical instructions instead of copying them into the packet, especially the charter. Persist only operating facts that need clarification or reinforcement. Prefer documented commands over broad repository exploration and stop discovery once the packet is runnable. If the repository has no canonical quality guidance, record that fact; do not invent a project-wide quality bar for the charter or reviewer.
-
-If the base, existing-change ownership, target checkout, destructive-data choice, or delivery mechanism is materially ambiguous, ask rather than guess.
-
-### Prepare the working location
-
-During preflight, inspect and propose the working mode, base, and location. Draft packet documents may be created and revised immediately for human review. Creating a branch or worktree is also preparation rather than dispatch, but avoid unnecessary setup before the target is understood. Apply the selected mode:
-
-- **In-place mode:** work in the invoked checkout and branch. Record checkout path, branch, integration base ref and commit, initial HEAD, pre-existing state, and exact review diff in `operations.md`. Keep unrelated existing changes out of Relay commits.
-- **Fresh-worktree mode:** create a new branch and worktree from the recorded base unless the task names another target. Follow the repository's existing worktree placement; otherwise use a clear sibling location. Draft the packet in the preparation session's checkout until the target exists, then move it intact into the worktree before dispatch and set every handoff's `cwd` to that worktree. Record the dispatching checkout's state as well as worktree path, branch, and initial HEAD in `operations.md`.
-- **Explicit existing location:** when the task names an existing checkout or worktree, use it and record the same operating facts as in-place mode.
-
-In fresh-worktree mode, make leg 1 setup-only when bootstrap is required: perform the recorded bootstrap, confirm success and allowable working-tree state, then hand off without inspecting or implementing the task. If no bootstrap is needed, dispatch the first substantive leg.
-
-Treat the Relay packet as operational state, not delivery work. Use `.pi-web/relays/<name>/` in the drafting checkout during preparation and in the selected target checkout before dispatch. Keep it outside delivery commits and the reviewed diff through an existing ignore rule, a local Git exclusion, or another non-delivery location.
-
-### Write goal and operations separately
-
-Keep `charter.md` short and destination-focused. Record:
-
-- Relay identity;
-- the interpreted goal and observable finish line in plain language;
-- minimum outcome acceptance;
-- in-scope edges, explicit non-goals, directly affected behavior that must remain unchanged, and material assumptions or human decisions.
-
-Do **not** put a quality bar, technical design, expected files or subsystems, verification matrix, edge-case inventory, failure taxonomy, review checklist, or copied project standards in the charter. Reviewers apply the repository's current canonical skills and documentation directly, so the charter does not need to predict or paraphrase them.
-
-Write the profile's mechanics to `operations.md` instead:
-
-- packet identity and `relay-runner` as the profile required in every leg and handoff;
-- implementation-first leg sizing and outcome-led task selection under this profile, with route assumptions provisional and no fixed leg count;
-- pointers to canonical repository instructions and applicable project skills;
-- checkpoint and transition policy;
-- packet root, working location, branch, immutable base commit, initial HEAD, pre-existing state, packet isolation, and exact review range;
-- focused and full verification commands;
-- commit policy: every leg that changes delivery files commits all and only its changes, including intended new files, before handoff, while packet updates remain isolated;
-- the two-attempt normal whole-work review/remediation policy, exceptional third-attempt contingency, and review-decision continuity;
-- delivery mechanism; and
-- intervention signal and triggers supplied by this profile, the user, or repository.
-
-### Require shared understanding and approval
-
-The preparation prompt owns the interactive preflight. Create and iteratively update goal-focused `charter.md`, profile-owned `operations.md`, compact `status.md`, and append-only `log.md` as reviewable drafts. Mark status **Draft — awaiting approval; not dispatched**. Use `ask_user` when an answer changes the goal, an edge, target, destructive-data choice, delivery mechanism, working location, or non-obvious base. Ask related questions together. This profile supplies routine mechanics, so the user approves the prepared Relay rather than designing the protocol.
-
-After pointing the user at the final drafts, summarize the goal/edges, operating setup, and first bounded leg, then explicitly ask **Approve and dispatch**, **Revise**, or **Do not dispatch**. Never infer dispatch approval from the initial request, permission to create drafts, or the absence of objections. A material change after approval invalidates it and requires another review. On revision, update and re-present the drafts. On refusal, mark status not dispatched, append the decision, and stop. Drafting and checkout setup may happen before approval; `spawn_session` may not.
-
-### Approved-dispatch workflow
-
-After explicit approval, finalize all four documents, mark the packet approved, and record approval in status and log. Seed active leg tracking with last completed leg 0, the first leg identifier/task, targeted context, blockers, `review attempts: 0`, `third-attempt contingency: unused`, and any active pointers. In fresh-worktree mode, move the packet into the target worktree, update recorded paths and location facts, and remove the stale drafting copy before handoff.
-
-Dispatch exactly one first leg with `spawn_session`, after all state is durable in its final location. Use the selected checkout/worktree as `cwd`. After `spawn_session` returns, report the Relay name, packet path, location and branch, interpreted finish line and material non-goals, delivery target, first leg, and dispatch confirmation. Perform no further operational action and never promise a total leg count.
-
-## Run every leg
-
-Use this loop:
-
-1. Read `charter.md`, `operations.md`, `status.md`, and only targeted context they reference. Then load canonical project skills applicable to this leg.
-2. Confirm that the prompt's leg identifier, status baton, working location, branch, and blockers are consistent. Resolve small baton defects with targeted inspection; intervene instead of broad archaeology or guessing about intent.
-3. Use status's next outcome as the starting point. Revise inherited sequencing or design when a simpler connected slice better advances it. Safe implementation splits within the charter are runner decisions, not approval requests. If the intended outcome remains ambiguous or falls outside the finish line, intervene.
-4. Re-anchor to the finish line and perform the containment check. Do exactly one bounded slice. Do not audit unrelated code, execute the next nominal leg too, or expand scope under the guise of quality.
-5. Run every focused check meaningful for the slice and report exact results. Before whole review, run the full verification named by `operations.md`. Never describe failed, skipped, or incomplete verification as passing.
-6. Make delivery changes durable under the operations record's commit policy without absorbing unrelated state. Keep packet-only writes out of delivery commits.
-7. Update status with the observable progress, completed and next leg identifiers, next outcome, existing seam to connect, concrete constraints, remaining unconnected work, targeted context, verification state, blockers and active transition/review pointers. Keep route choices provisional. Append the concise leg entry to the log before stopping or handing off.
-8. Stop without spawning when Relay completion is recorded, the leg is blocked, or an intervention trigger fires. When the chartered outcome is implemented but required review, approval, or delivery remains, name that lifecycle work as the next leg instead of stopping. Surface the intervention signal clearly. Otherwise hand off exactly once at the end with `spawn_session`.
-
-Use this handoff shape, substituting the actual paths and next identifier:
-
-```text
-Relay "<name>" leg <identifier> begins now.
-
-Work under the Relay method with the `relay-runner` operational profile.
-Load the `relay` and `relay-runner` skills, then read:
-- .pi-web/relays/<name>/charter.md
-- .pi-web/relays/<name>/operations.md
-- .pi-web/relays/<name>/status.md
-
-Do not read log.md end-to-end. Use only targeted entries referenced by charter.md, operations.md, or status.md.
-Run exactly one outcome-led leg under the profile's implementation-first rules. Use status's next outcome and connection priority; adapt the route within the charter. Make work and packet updates durable, then either hand off once or stop with the recorded intervention signal.
+```json
+{
+  "packet": ".pi-web/relays/<name>",
+  "leg": "2",
+  "cwd": "/absolute/path/to/checkout"
+}
 ```
 
-## Whole-work review and remediation
-
-Run whole-work review immediately before delivery and only after implementation and verification are believed complete and no transition remains active.
-
-Approval means the reviewed evidence reasonably demonstrates the chartered finish line under the repository's canonical quality guidance; it does not claim the work is perfect or free of every possible defect. Reviewers are not expected or rewarded to produce findings. A clean approval is the correct result when no concretely supported blocker is found.
-
-Use **two normal whole-work review attempts** from implementation-complete through delivery: the initial review and, only when needed, one post-remediation or pre-delivery re-review. A third review is an exceptional contingency, not routine capacity or a target. Invoke it only under the attempt 2 finding rule below or when delivery finds that materially changed review inputs made the prior approval stale. Record `review attempts: N` and `third-attempt contingency: unused` in status, changing the contingency field to `invoked — <reason>` before using it. Append each attempt, base, and HEAD to the log. Focused subreviews consolidated by one reviewer are part of one attempt, not separate attempts.
-
-Attempt 1 is the only broad, proportionate review pass. Report its concretely supported blockers together rather than serializing already-known concerns across later attempts; this calls for a proportionate pass, not an exhaustive search. Later reviews still judge the exact delivery diff as a whole, but carry prior decisions forward and focus on remediation, changed evidence, and regressions. Do not restart review from zero, expand the audit surface, or apply a newly stricter standard because another attempt is available.
-
-For each attempt:
-
-- Review the exact delivery diff recorded in `operations.md` against the charter's goal and edges and the repository's canonical quality instructions. Do not derive a technical bug-hunting checklist from incidental charter wording.
-- Keep the reviewer report-only for implementation and delivery artifacts. Its only writes are packet updates needed to record review and handoff.
-- Confirm the full verification required by `operations.md` at the reviewed HEAD and record exact results.
-- Approve when no blocking finding meets the evidence threshold below, even if non-blocking limitations or theoretical risks remain. Record exact reviewed base and HEAD, point status at the approval, and name delivery as next.
-- When attempt 1 has blocking findings, record them in risk order in the log, name one coherent remediation leg in status with a targeted pointer, and dispatch it. Remediation runners resolve the recorded blockers in bounded slices and dispatch attempt 2 only after the attempt 1 report has been addressed; do not spend another whole-work review merely to reveal the next already-known item.
-- When attempt 2 has a blocking finding, do not automatically consume attempt 3. Invoke the remediation contingency only when concrete evidence shows that an attempted remediation reasonably expected to resolve a blocker did not, remediation introduced an in-scope regression, or materially new evidence reveals a blocker that could not reasonably have been assessed earlier—and one bounded remediation is likely to resolve it. Record that justification, mark the contingency invoked, and dispatch one coherent remediation leg followed by attempt 3. Expanded scrutiny, a changed standard, deferred already-available evidence, or speculative possibility does not qualify. If a genuine blocker remains but the contingency is not justified or bounded, intervene.
-- When exceptional attempt 3 still has any blocking finding, stop the automatic loop. Record the unresolved findings and exact decision needed, raise the human intervention signal, and do **not** dispatch remediation or a fourth review. A human may accept an authorized risk, change the agreement, stop the Relay, or explicitly grant a bounded additional remediation/review attempt.
-
-The reviewer chooses proportionate independent review and records that decision. Independent subreviews are optional; use them only when a specific changed surface benefits from focused expertise, not to create review theater or increase the chance of finding something. The reviewer may use `spawn_subsession` for report-only focused reviews, then `yield_to_subsessions` and consolidate. Subreview prompts must identify repository, base and exact diff, the charter's goal and edges, canonical quality instructions, and the prohibition on all writes including packet changes. The consolidating reviewer is the sole packet writer. The Relay handoff still uses one `spawn_session` only at the end of the leg.
-
-A blocking finding needs concrete evidence of an in-scope defect: for example a reproduced failure, a failing relevant check, a specific execution path that violates the approved outcome, or a clear breach of a material contract, invariant, security, authorization, or data-integrity boundary. Mere possibility, stylistic preference, optional hardening, hypothetical future requirements, or “there could be an edge case” is not blocking. If proportionate targeted inspection cannot establish applicability and impact, classify the concern as non-blocking or omit it rather than forcing remediation.
-
-Review cannot over-specify the agreement. Decide materiality from the charter's goal and edges and the repository's canonical guidance, not from a reviewer-created standard. A concern outside those authorities is non-blocking or out of scope even when it describes a possible improvement. Non-blocking findings do not prevent approval or consume a remediation leg. Do not turn review into an audit of unrelated pre-existing shortcomings.
-
-### Review-decision continuity
-
-Create `review-decisions.md` only when a finding disposition must survive into later reviews. Point to it from status continuously through remediation and delivery; later reviewers read it instead of reconstructing history from the log.
-
-Give recurring findings stable identifiers. Record concern, disposition, concise rationale, evidence, authority, applicability, and revisit conditions. A remediated decision cites the fixing commit and verification. Not-applicable cites concrete evidence. Accepted-risk or out-of-scope cites an exact charter edge, canonical project guidance, or explicit human direction. Do not create speculative risk analyses merely to populate the register.
-
-Do not duplicate an existing finding. Honor supported decisions while facts remain unchanged, but reopen for materially new evidence, changed applicability, or a demonstrable error or charter conflict. Record what supersedes the old decision. A reviewer cannot unilaterally waive an in-scope defect.
-
-Keep the register compact and current. It is subordinate to the charter: changing the goal, minimum outcome acceptance, or a scope edge requires human agreement, a charter update, and a log entry.
-
-## Delivery finish
-
-The final leg performs only the delivery mechanism recorded in `operations.md`.
-
-1. Read the targeted approval entry cited by status.
-2. Verify that the integration base still resolves to the reviewed base commit, HEAD equals the reviewed HEAD, and the working tree matches the allowable state recorded in `operations.md`, normally clean apart from the packet.
-3. If the base advanced or expected in-scope work changed, intervene when the mismatch is unrelated, unexpected, or of unclear ownership. Otherwise dispatch a fresh whole-work review when a normal attempt remains. After two attempts, invoke the exceptional third only when the changed inputs materially invalidate the prior approval and a targeted review can assess the new exact range; record that reason before dispatch. If neither condition applies, intervene.
-4. Create or update the recorded pull/merge request, push the branch, produce the agreed patch, or leave the agreed clean committed local branch. Do not invent delivery infrastructure the repository does not use.
-5. State what changed and why, behavioral or contract changes, migration or deployment ordering when applicable, and exact verification with results.
-6. Record the delivery result—URL, pushed branch, patch path, or local commit/branch—in status and log before declaring completion. Required push, authentication, or review-tool failure is intervention, not completion.
-
-## Intervention triggers
-
-Stop, update status, append the log, surface the intervention signal recorded in `operations.md`, and do not spawn when:
-
-- the finish line or a stable outcome must change without explicit human agreement;
-- the environment is unusable;
-- destructive-data behavior is ambiguous;
-- a product or business decision lies outside the charter;
-- proceeding would knowingly weaken a material invariant or security/authorization boundary;
-- unexpected unrelated branch changes make ownership or the review range unclear;
-- required delivery or authentication fails;
-- review remains blocked after the normal attempts and the third-attempt contingency is unavailable or exhausted;
-- the finish line is infeasible; or
-- another user-, repository-, charter-, or operations-defined trigger fires.
+The tool validates the saved packet, generates the handover instructions, and records explicit Relay identity and a predictable session name. It accepts no free-form prompt and starts an independent session; do not substitute a generic session tool or tracked subsession. Omit `model` and `thinkingLevel` to inherit them unless the human instructed otherwise; keep any relay-wide instruction in the packet.
 
-Ordinary implementation defects stay within the agreed route and review findings go through remediation. Neither justifies changing scope, ignoring canonical project guidance, or relabeling unexpected breakage as transitional.
+`dispatch_relay` is the final operational action. After it returns, give only a brief handoff summary: no further tool use, packet writes, work, or downstream supervision. If the tool is unavailable or dispatch fails, report the failure rather than claiming the next leg started.

package/dist/pi-packages/workflows/browser/pi-web-plugin.js

@@ -0,0 +1,33 @@
+// Generated from pi-packages/workflows/browser/pi-web-plugin.ts. Do not edit directly.
+function canPrepareWorktreePrompt({ state, prompt }) {
+    const session = state.selectedSession;
+    return state.mainView === "chat"
+        && state.selectedWorkspace !== undefined
+        && session !== undefined
+        && !session.archived
+        && !session.pending
+        && prompt.getText() === "";
+}
+const plugin = {
+    apiVersion: 4,
+    name: "Workflows",
+    activate: () => ({
+        contributions: {
+            actions: [{
+                    id: "worktree.create",
+                    title: "Create Worktree",
+                    description: "Prepare /worktree; describe its purpose and/or base branch before sending",
+                    group: "Workflows",
+                    enabled: canPrepareWorktreePrompt,
+                    disabledReason: () => "Select an active conversation in Chat with an empty prompt first.",
+                    run: (context) => {
+                        if (!canPrepareWorktreePrompt(context))
+                            return;
+                        context.focusPrompt();
+                        context.prompt.insertText("/worktree ");
+                    },
+                }],
+        },
+    }),
+};
+export default plugin;

package/dist/pi-packages/workflows/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@jmfederico/pi-web-workflows",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Opinionated PI WEB workflow prompts and shortcuts, starting with named Git worktree creation.",
+  "keywords": ["pi-package"],
+  "pi": {
+    "prompts": ["./prompts"]
+  },
+  "piWeb": {
+    "plugins": [
+      {
+        "id": "workflows",
+        "defaultEnabled": true,
+        "browserRoot": "browser",
+        "module": "browser/pi-web-plugin.js",
+        "machineSpecific": true
+      }
+    ]
+  }
+}

package/dist/pi-packages/workflows/prompts/worktree.md

@@ -0,0 +1,12 @@
+---
+description: Create a Git worktree named for its purpose
+argument-hint: "Purpose and/or base branch"
+---
+
+Create a Git worktree named for the user's purpose. Use the user-requested base, otherwise the current worktree's HEAD. If no purpose or description is provided, ask for one.
+
+The user's input is within the `<worktree_request>` tags below.
+
+<worktree_request>
+$ARGUMENTS
+</worktree_request>