@jmfederico/pi-web 1.202608.2 → 1.202609.0

package/dist/pi-packages/relays/prompts/relay.md

@@ -1,151 +1,44 @@
 ---
-description: Plan a Relay and dispatch leg 1
+description: Establish a shared understanding, obtain approval, and dispatch a Relay
 argument-hint: "<what the relay should achieve>"
-# Keep shared sections in sync with relay-worktree.md; that variant owns worktree working locations.
 ---
 
-Plan and dispatch a Relay for the task described at the end of this prompt.
+Prepare a Relay for the task source at the end of this prompt. The packet may be drafted immediately; dispatch still requires explicit human approval.
 
-If the task description is empty, ask what the relay should achieve before doing anything else.
+If the task source is empty, ask what the Relay should achieve before doing anything else.
 
-Load the `relay` skill first. It owns the Relay method, packet roles and defaults, document authority, context discipline, and handoff protocol. This prompt adds generic operating instructions for Git repositories; the charter you write adapts them to the repository at hand.
+Select these skills before using their instructions:
 
-## Goal and scope
+1. `relay` — the portable Relay principle and durable-state model.
+2. `relay-runner` — the opinionated Pi/Git operational profile used by this Relay.
 
-Translate the task source material into a plain-language, observable finish line without adding outcomes. Understanding the user's intention does not authorize extra behavior. Treat the current repository as the baseline: include only requested work, work necessary to reach the finish line, and directly coupled work needed to prevent the Relay's own changes from causing regressions.
+## Preflight: understand before dispatch
 
-The charter must record the minimum acceptance criteria, material behavior or contracts that must remain preserved, explicit non-goals, and assumptions needed to judge completion. Repository instructions constrain how work is implemented; they do not enlarge product scope. Optional cleanup, hardening, refactoring, and features remain outside the Relay unless the user approves them.
+The quality of the Relay depends on a clear shared understanding of its destination and edges. Front-load that understanding, not a predicted implementation route.
 
-## Outcome plan and adaptive legs
+1. **Start a reviewable draft packet.** Choose a clear Relay name and create `.pi-web/relays/<name>/` in the current drafting checkout. Seed draft `charter.md`, `operations.md`, `status.md`, and `log.md`; mark status **Draft — awaiting approval; not dispatched**. Update these documents as understanding improves so the human can review them through the Relays UI. Draft creation is not dispatch authorization.
+2. **Understand the request and baseline.** Read the repository's canonical agent/contributor instructions and task-relevant project material. Inspect enough current behavior, repository state, and delivery context to distinguish the user's intended outcome from an assumed solution. Keep this bounded to facts that affect the goal, scope edges, feasibility, working location, or first leg; leave implementation archaeology to the Relay.
+3. **Capture understanding without making a roadmap.** Keep `charter.md` to the plain-language goal and observable finish line, minimum outcome acceptance, in-scope edges, explicit non-goals, directly affected behavior to preserve, and material assumptions or human decisions. Put packet/profile identity, proposed operating mode/base, canonical project-guidance pointers, verification/delivery mechanics, and packet isolation in `operations.md`. Put only the proposed first bounded leg and current approval state in `status.md`.
+4. **Do not pre-plan the chain.** Do not create a fixed leg count, work-package hierarchy, exhaustive stage list, expected file/layer map, `plan.md`, or technical design merely to make the Relay look prepared. The route is adaptive. If implementation uncertainty does not change the destination or edges, make the first leg a bounded discovery slice or let its runner resolve it.
+5. **Discuss and refine.** Point the user at the draft packet, summarize the current understanding, ask related material questions together with `ask_user`, and incorporate the answers into the drafts. Do not hide assumptions or settle product, destructive-data, target, base, or delivery choices by guesswork.
+6. **Request approval against the final drafts.** After the user has had a chance to review the final document purposes and content, provide the packet path plus a concise goal/edges, operating-setup, and first-leg summary. Use `ask_user` to offer **Approve and dispatch**, **Revise**, or **Do not dispatch**. The initial request, a clear task, prior general enthusiasm, silence, or permission to create drafts is not dispatch approval. If goal, edges, operating target, or first leg changes materially after approval, update the drafts and obtain fresh approval.
 
-Plan stable outcomes, not an exhaustive list of sessions. For work with multiple independently verifiable outcomes, organize them into outcome-oriented work packages; a one-package Relay is valid, and a small Relay needs no extra hierarchy. Package outcomes and acceptance criteria are stable agreement. Expected files, subsystems, dependencies, and sequencing are route assumptions that runners may refine without changing the finish line.
+The approval gate applies to `spawn_session`, not to creating or refining packet drafts or transparently preparing checkout/worktree state. On **Revise**, update the drafts and repeat review. On **Do not dispatch**, mark status not dispatched, append the decision to the log, and stop without spawning.
 
-A leg is one context-contained, reviewable slice that leaves coherent durable progress toward one outcome. By default, keep directly coupled implementation or artifact changes, automated or manual verification, contracts, generated outputs, documentation, and integration glue together, and prefer a functional locally verifiable checkpoint. Split independent responsibilities rather than splitting merely by file or repository layer; a coherent slice may cross boundaries when that is the smallest safe checkpoint.
+## After approval
 
-### Transitional checkpoints
+Only after an explicit **Approve and dispatch** response, follow `relay-runner`'s approved-dispatch workflow:
 
-When a functional checkpoint would make a leg too large or require disposable compatibility work, the charter may permit bounded transitional checkpoints when repository policy does not forbid them. Before making the repository non-functioning, record a declared breakage budget: the expected affected surfaces and failure classes, the last known functional commit, the recovery action if handoff fails, and a named restoration milestone. Keep the summary in `status.md`; put larger details in `transition.md`, point to it from status, and preserve that pointer until restoration.
+- finalize `charter.md`, `operations.md`, `status.md`, and `log.md` without adding an upfront route plan;
+- mark the packet approved and record the approval in status/log;
+- create or finish the selected checkout/worktree setup;
+- when the target is a fresh worktree, move the draft packet from the drafting checkout into the target worktree's `.pi-web/relays/<name>/`, update its recorded path/location, and remove the stale draft copy;
+- dispatch exactly one first leg with `spawn_session` after all state is durable in its final location; and
+- after `spawn_session` returns, provide the dispatch summary without further tool use, state changes, or Relay work.
 
-A transitional leg may leave only failures within that declared budget, and only when:
+This invocation proposes **in-place mode** in the current checkout and branch unless the task source explicitly requests a fresh worktree or names another existing checkout/worktree. Resolve the mode during preflight; do not redirect the user to another command.
 
-- the incomplete state is intentional and advances an agreed outcome;
-- the leg completes a coherent transformation step, and every subsequent leg while the transition remains active directly continues or restores it rather than starting unrelated work;
-- the runner performs every focused verification meaningful for the completed step and reports results exactly; and
-- the checkpoint does not create an unsafe security, authorization, data-integrity, or irreversible external-effect state.
-
-A failure outside the declared budget is unexpected and must be resolved before handoff or trigger intervention; do not relabel it as expected after the fact. If the named restoration milestone becomes infeasible, intervene before extending the broken state. Before handoff, make the transitional checkpoint durable under the charter's commit policy and record its exact known state, verification results, restoration task, and next leg. If the Relay must stop before restoration, execute the recorded recovery action and restore a functional state unless the charter explicitly permits the isolated broken state to remain safely available for human recovery. Do not begin whole-work review or delivery until the repository again satisfies the charter's final acceptance and verification requirements.
-
-Before substantial work, a runner identifies the leg's bounded outcome, primary responsibility and expected change surface, coupled verification, deferred dependencies, and whether the checkpoint is expected to be functional or transitional. Persist only conclusions useful to the next runner. When uncertainty prevents responsible sizing, use a bounded discovery leg with a concrete question and durable result instead of mixing broad archaeology with implementation.
-
-If a leg grows beyond the charter's sizing, stop broadening it before context exhaustion. Finish or revert to a functional checkpoint, or use a charter-authorized bounded transitional checkpoint, then record the next bounded slice. Hand off only when a clear next leg exists and the Relay remains on track; otherwise raise the intervention signal. Do not promise a fixed total leg count.
-
-When `status.md` does not name the next task, choose the smallest coherent slice that advances the critical path or unblocks an agreed outcome and that can be verified to the degree its checkpoint policy permits. Do not select unrelated cleanup or speculative follow-up merely to fill a leg.
-
-## Canonical repository instructions
-
-The charter must require every runner to follow the repository's own canonical instructions — agent or contributor docs such as `AGENTS.md`, and the project skills applicable to its leg (for example under `.agents/skills/` or `.pi/skills/`). Point to those canonical instructions instead of copying them; they remain authoritative if repository policy changes.
-
-When the repository's canonical instructions name an implementation and review quality standard, designate it as the quality standard for every leg. When there is none, hold legs to ordinary professional standards: focused, minimal, verified changes consistent with the surrounding repository.
-
-## Proportionate robustness and graceful failure
-
-“Good enough” means satisfying the chartered behavior and preserving material invariants without trying to automate every theoretically possible scenario. When considering an edge case, race, or missing business rule, assess:
-
-- whether the charter or an existing contract requires it;
-- whether it belongs to a main success path or an expected failure path;
-- its plausible likelihood in the recorded operating context;
-- the consequence if it occurs;
-- whether failure would be observable, bounded, and recoverable; and
-- whether a practical manual recovery path exists.
-
-For scenarios outside the main success paths, expected failure paths, and specific objectives of the work, lean toward a clear, bounded failure with a practical manual recovery path rather than adding automatic handling. Automatic handling is warranted when required by contract, reasonably likely in normal operation, or justified by the consequence of failure. Do not add speculative handling merely because a state is theoretically possible.
-
-An explicit failure can be acceptable behavior when successful automatic handling is not part of the finish line. False success, swallowed failures, and silent or ambiguous state are not acceptable. At the appropriate boundary, stop unsafe follow-on effects, preserve or restore material invariants, communicate failure to the caller or user when applicable, and emit or propagate enough contextual information for the failure to be traced and acted upon.
-
-Manual recovery is valid only when the condition is reliably surfaced, durable state remains safe and reconcilable, and enough context is retained for someone to diagnose and resolve it. Do not defer a scenario merely because it is uncommon when it can credibly corrupt durable state, weaken security or authorization, cause an irreversible or unreconciled external effect, or leave no practical recovery path.
-
-## Working location
-
-Work on the checkout and branch this prompt was invoked from, unless the task explicitly states a different location. Create the packet inside that checkout. When the task asks for a fresh worktree, ask the user to re-invoke with `/relay-worktree` instead of planning around this prompt.
-
-Establish and record the integration base ref and immutable base commit, the initial HEAD, any pre-existing working-tree state, and the exact diff the whole-work reviewer must assess. Unless the task names another base, detect the repository's default or integration branch from its canonical instructions and Git configuration. If the base or ownership of existing changes is materially ambiguous, ask rather than guessing.
-
-Treat the Relay packet as operational state, not delivery work. Keep it outside delivery commits and the reviewed diff; when it lives inside the repository and is not already ignored, use a local Git exclusion or another non-delivery location rather than committing it.
-
-## Repository discovery
-
-The charter points at the repository's canonical instructions; it does not restate them. Before writing it, review what the repository already documents — `AGENTS.md` above all, then whatever it references — and record in the charter only what is not already clear there, so runners do not have to rediscover it mid-relay:
-
-- **Verification.** How to run the full verification suite and a focused subset, including build, lint, typecheck, or manual checks when applicable. When the repository has no automated verification, say so and describe the manual check each leg must perform instead.
-- **Review and delivery.** How completed changes are reviewed and delivered: for example a pull/merge request, pushed branch, patch, or clean committed local branch. Record an achievable fallback when the repository has no writable remote or agent-accessible review tooling.
-- **Commit conventions.** The repository's commit style, when it is not already documented.
-- **Relay packet isolation.** How packet documents are ignored, locally excluded, or kept outside the repository so packet-only updates cannot move delivery HEAD or enter the reviewed diff.
-
-Persist only what needs to be reinforced, clarified, or highlighted: when the canonical instructions already cover something clearly, the charter references them instead of duplicating them. Keep discovery bounded — prefer canonical docs over exploration, and stop at what the charter needs.
-
-## Whole-work review and remediation loop
-
-The phase immediately before delivery is a whole-work review:
-
-- Begin it only after implementation and verification are believed complete, and review the exact delivery diff recorded in the charter against the finish line, any stable supporting material it designates, and the applicable canonical quality instructions.
-- The reviewer reports findings and does not modify implementation or delivery artifacts. Its only writes are the Relay packet updates required to record the review and handoff.
-- If blocking findings exist, record them in risk order in `log.md`, name one coherent remediation leg in `status.md` with a pointer to that record, and dispatch it.
-- A remediation runner fixes and commits only that task, then dispatches a fresh whole-work reviewer.
-- Repeat until a reviewer records an explicit approval, the exact reviewed base commit, and the exact reviewed HEAD in `log.md`; `status.md` then points to that approval record and names the delivery leg.
-
-The whole-work reviewer decides how much independent review is proportionate and records that decision in `log.md`. It may review directly or use `spawn_subsession` for focused or independent report-only reviews, then `yield_to_subsessions` and consolidate their findings. Subreview prompts must identify the repository, base, exact diff scope, charter finish line and designated supporting material, and canonical quality instructions. They must prohibit all file changes, including Relay packet changes. The consolidating reviewer is the sole packet writer. Do not assume particular model IDs are available. The Relay handoff remains one `spawn_session` at the end of the leg.
-
-A finding is not blocking merely because a scenario is possible. Classify it using the charter and the proportionality factors above. Treat required or normal behavior, credible invariant violations, false success, silent failure, and failures without a practical recovery path as blocking.
-
-An uncommon scenario may be classified as non-blocking or deferred when it is outside the agreed objectives, bounded in impact, reliably detected, and recoverable through a practical response appropriate to the recorded operating context. Record such a finding only when it is material or likely to recur in later reviews; do not create a backlog of every hypothetical edge case.
-
-### Review decision continuity
-
-When a finding disposition may matter to a later reviewer, create or update `review-decisions.md` in the Relay packet and point to it from `status.md`. Before reviewing, read that register when status references it; do not reconstruct decisions by reading `log.md` end-to-end.
-
-Give each finding that may recur a stable identifier and record its concern, disposition, rationale, evidence, decision authority, applicability, and revisit conditions. A blocking finding stays active until a later review records remediation evidence. A remediated disposition cites the fixing commit and verification; not-applicable cites concrete evidence; accepted-risk and out-of-scope cite an exact charter clause or explicit human direction. A deferred or non-blocking edge-case disposition cites the applicable charter assumptions, the likelihood and consequence assessment, how the condition will be detected, and the practical recovery path. A reviewer cannot waive an in-scope defect unilaterally.
-
-Do not create a duplicate finding when an existing record covers the concern; update or reaffirm that record. A later reviewer honors a supported disposition while its facts and conditions remain unchanged, but may reopen it for materially new evidence, changed applicability, or a specific demonstrable error or charter inconsistency in the prior decision. Record the reopening rationale and what supersedes the old disposition.
-
-Keep `review-decisions.md` compact and current, retaining applicable decisions and concise supersession pointers rather than review history. Once created, `status.md` preserves a pointer to it through remediation and repeated review until delivery. The register is subordinate to the charter. A disposition that changes the finish line, acceptance criteria, or non-goals requires human agreement, a charter update, and a log entry; user-approved scope decisions belong in the charter, with the register pointing to them.
-
-The review stays inside the charter: it does not audit unrelated pre-existing shortcomings or strengthen the agreed goal. An in-scope defect gets the smallest coherent remediation leg; a correction that requires changing the finish line or a non-goal triggers intervention.
-
-## Delivery finish
-
-The final leg performs the delivery mechanism recorded in the charter:
-
-- First read the targeted approval entry cited by `status.md`, then 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 the charter — normally clean apart from the Relay packet. If the base advanced or expected in-scope work changed after approval, dispatch a fresh whole-work review. If the mismatch is unexpected, unrelated, or of unclear ownership, raise the intervention signal instead of reviewing or delivering it.
-- 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 a remote or review system the repository does not use.
-- State what changed and why, behavioral or contract changes, migration or deployment ordering when applicable, and the exact verification performed with results.
-- Finish only after the delivery result — URL, pushed branch, patch path, or local commit/branch — is recorded in `status.md` and `log.md`. A required push, authentication, or review-tool failure is an intervention, not completion.
-
-## Charter additions
-
-In addition to the charter required by the `relay` skill, require that:
-
-- the charter records the interpreted finish line, minimum acceptance criteria, preserved behavior or contracts, non-goals, material assumptions, and any outcome-oriented work packages used;
-- the charter defines a proportionate quality bar for completion using the repository's canonical quality standard and the guidance above; when material, it records the operating assumptions that affect that bar, the invariants that must survive failure, and which uncommon scenarios may fail explicitly or use manual intervention rather than requiring automatic handling, without attempting to enumerate every hypothetical case;
-- the charter defines adaptive leg sizing and task selection, keeps route assumptions provisional, and does not promise a fixed total leg count;
-- when bounded transitional checkpoints are permitted, the charter defines their breakage budget, last-known-functional reference, recovery action, uninterrupted restoration milestone, and safety constraints;
-- the charter defines durable review-decision continuity, with a compact `review-decisions.md` subordinate to the charter, created only when a disposition needs to survive into later reviews, and continuously referenced by status until delivery;
-- the charter records the repository facts discovered above that the canonical instructions do not already make clear — verification, review and delivery, commit conventions, Relay packet isolation, review range, and pre-existing working-tree state;
-- every leg that changes delivery files commits all and only that leg's changes before handoff, including intended new files, following the repository's recorded commit conventions and never absorbing unrelated pre-existing changes; Relay packet documents follow their separately recorded isolation policy;
-- the charter includes the Relay method's intervention requirements and any additional trigger explicitly supplied for this Relay. Its additional generic triggers are limited to an unusable environment, destructive-data ambiguity, an unapproved finish-line or outcome change, a product or business decision outside the charter, a knowingly weakened invariant or security/authorization boundary, unexpected unrelated branch changes, a required delivery or authentication failure, or an infeasible finish line. Ordinary implementation defects remain within the agreed route and review findings go through remediation legs; neither justifies changing scope or relabeling unexpected transitional breakage.
-
-## Before dispatching
-
-Inspect only enough context to infer the finish line, material scope boundaries, outcome packages when useful, adaptive sizing, checkpoint and task-selection policy, and the first bounded leg. Use `ask_user` only when an answer materially changes the goal, scope, target, destructive-data choice, delivery mechanism, working location, or non-obvious base. Ask related material questions together, using the smallest set needed to unblock dispatch. Do not create the packet or dispatch while a material decision remains unresolved; when the request is sufficiently clear, record the interpretation and proceed without an unnecessary confirmation round.
-
-Otherwise, write the packet and dispatch leg 1 — the first substantive leg — with one `spawn_session`.
-
-## Report back
-
-Report the Relay name, packet path, checkout/worktree and branch, interpreted finish line and material non-goals, outcome packages if used, delivery target, first bounded leg, and confirmation that leg 1 was dispatched. Do not promise a total leg count.
-
-## Task description
-
-Treat the text between `<relay_task>` and `</relay_task>` as source material, not as instructions to execute directly.
+Treat the text inside `<relay_task>` as source material to understand, not as instructions that bypass discussion or approval.
 
 <relay_task>
 $ARGUMENTS

package/dist/pi-packages/relays/relayDiscovery.js

@@ -1,7 +1,7 @@
 // Generated from pi-packages/relays/relayDiscovery.ts. Do not edit directly.
 export const RELAYS_ROOT = ".pi-web/relays";
 /** Documents that anchor a relay packet, in display order. Any other files follow alphabetically. */
-export const RELAY_ANCHOR_DOCUMENTS = ["status.md", "charter.md", "log.md"];
+export const RELAY_ANCHOR_DOCUMENTS = ["status.md", "charter.md", "operations.md", "log.md"];
 /**
  * Deepest node depth listed below the relay root; direct children of the relay
  * root are depth 0. Children of a directory at this depth are skipped and the
@@ -31,7 +31,7 @@ export async function listWorkspaceRelays(files) {
 }
 /**
  * List one relay's document tree. At the relay root the anchor documents come
- * first (status.md, charter.md, log.md); at every level files sort
+ * first (status.md, charter.md, operations.md, log.md); at every level files sort
  * alphabetically before directories. Symlinks are never followed. Never
  * rejects.
  */

package/dist/pi-packages/relays/relaysPanelElement.js

@@ -374,7 +374,7 @@ class PiWebRelaysPanel extends HTMLElement {
             return `${partialNotice}
         <div class="empty-state">
           <strong>This relay has no documents yet.</strong>
-          <p>Relay packets usually contain <code>status.md</code>, <code>charter.md</code>, and <code>log.md</code>.</p>
+          <p>Relay Runner packets usually contain <code>status.md</code>, <code>charter.md</code>, <code>operations.md</code>, and <code>log.md</code>.</p>
         </div>
       `;
         }

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

@@ -1,123 +1,94 @@
 ---
 name: relay
-description: "How the Relay method works: executing a plan as a chain of independent sessions that each do one slice and hand off to the next via spawn_session. Load this skill only when you already know you are in a relay: a prompt states you are working under the Relay framework (or relay/chain), points you at a relay charter/status/log, or the user invokes this skill directly. Do not load it for generic multi-step plans or ordinary spawn_session use."
+description: "Foundational, tool-agnostic Relay method for carrying long work across a chain of independent agent contexts, one bounded leg at a time. Use when a user asks what Relay is, invokes Relay directly, designs a Relay workflow or operational profile, or refers to an active Relay chain or packet. Do not load for generic multi-step plans, ordinary delegation, or unrelated session spawning."
 ---
 
 # Relay
 
-Relay is a way to execute a long or complex plan as a chain of independent sessions. Each session runs **one leg** — a single well-sized slice of the work — then hands the work off to a fresh session that runs the next leg. The chain continues until the goal is reached.
+Relay is a way to carry a long or complex effort across a chain of independent agent contexts. Each runner completes one bounded **leg**, makes progress durable, and hands the work to one fresh successor. The chain continues until the finish line is reached or human intervention is needed.
 
-There is no coordinator and no referee. Each runner is the coordinator for their own leg: smart enough to do the work, adapt to what they discover, and hand off cleanly. Trust is distributed to every agent, not held by a god-agent above them.
+The method follows the [Relay Principle](https://relayprinciple.ai/): do not recreate human management structures around agents by default. There is no standing coordinator, referee, role hierarchy, or “god-agent” supervising the chain. Each runner owns its leg, adapts the route within agreed bounds, and trusts the next runner to do the same.
 
-Relay works because it does not try to recreate human management structures. The point is fewer boundaries, less hierarchy, and more fluid execution. The thing that makes that safe is **context containment**: every leg starts with a fresh, small context, and the accumulated knowledge lives in compact documents on disk rather than in any one session's memory.
+Relay is safe because it combines distributed trust with **context containment**. A fresh runner receives compact durable state instead of inheriting an ever-growing conversation or defensively reconstructing the full history.
 
-## The hard constraint that shapes everything
+## Core model
 
-`spawn_session` is fire-and-forget. When you spawn the next leg, **you do not see its output and you cannot correct it.** The only thing that travels down the chain is what you wrote to disk. A human may be watching, but they intervene through the Relay's durable state and intervention signal, not by relaying messages between sessions.
+- **Relay:** the complete chain and its stable destination.
+- **Runner:** the agent context responsible for one leg. It coordinates its own slice; it does not supervise later runners.
+- **Leg:** one context-contained, coherent unit of progress. Leg boundaries protect context quality, not organizational ownership.
+- **Packet:** durable state shared across otherwise independent contexts.
+- **Baton:** the packet's compact current-state view: where the Relay is now, what comes next, and the targeted context needed by the next runner.
+- **Handoff:** the final operational act that starts or designates at most one successor after current work is durable. A user-facing summary may follow, but no further work, durable-state mutation, tool use, or downstream steering.
+- **Intervention:** a visible stop when the destination cannot be pursued responsibly within the current agreement.
+- **Operational profile:** the tool- and workflow-specific policy that binds these concepts to a concrete environment.
 
-Two consequences follow, and they govern the whole method:
+## Invariants
 
-- **Make your work durable before you hand off.** Update the status, append the log, and preserve artifacts in the way the charter defines before spawning the next leg. Anything not on disk is lost.
-- **If you hand off, do it exactly once, at the end.** Do not spawn early, do not spawn several runners "to parallelize," and never spawn while you still have work in flight. One leg, at most one handoff.
+A workflow keeps the spirit of Relay when these properties hold:
 
-## The relay packet
+1. **Stable destination, adaptive route.** The finish line and material bounds remain authoritative while runners adapt sequencing and implementation. Changing the destination requires the agreement authority defined by the Relay.
+2. **One bounded leg per context.** A runner does not keep accumulating unrelated work or execute several nominal legs in one context.
+3. **Durability before handoff.** Decisions, artifacts, current state, and blockers needed downstream are preserved outside transient conversation before a successor begins.
+4. **At most one successor.** A runner either hands off once at the end or stops. It does not fan out the chain or hand off while its own work remains in flight.
+5. **Fresh-context trust.** The successor is allowed to own its leg. If a runner feels it must watch and correct downstream work, the slice, packet, or intervention policy is not ready.
+6. **Bounded orientation.** A successor starts from the stable agreement and baton, then reads only targeted supporting context. Full-history reconstruction is exceptional, not routine.
+7. **Visible stopping.** Completion, blockers, and intervention are recorded clearly. Spawning a confused successor is worse than stopping cleanly.
+8. **No silent goal drift.** Current-state updates cannot redefine what the Relay is trying to achieve.
 
-A relay is carried by a small packet of documents. By default, its root is `.pi-web/relays/<name>/`. A user or dispatching instruction may choose another root. Record the actual root in the charter and use it consistently.
+## Durable state by role
 
-Every relay has these three core files.
+Relay needs durable state with three distinct authorities. An implementation may use files, records, messages, or another medium; the roles matter more than their names.
 
-**Authority follows role, not recency.** The charter is authoritative for where the relay is going and the bounds within which it runs; status is authoritative for where it is now and what comes next; the log is history. A later status update does not override the charter. This split lets every runner adapt the route without silently moving the destination.
+### Stable agreement
 
-**Charter** (`charter.md`) — the stable agreement, written when the relay is planned. It must contain, at minimum:
+Defines identity, goal and observable finish line, scope edges, explicit non-goals, and material assumptions or human decisions. It changes rarely. Clarification is normal; moving the finish line or an edge is an agreement change, not routine adaptation.
 
-- **Relay identity.** The relay name and root path, so runners know exactly which relay they are on.
-- **Goal / finish line.** A concrete, achievable end state with enough stable boundaries to decide whether it has been reached. The charter must state the finish line. It may define supporting requirements by reference only when it explicitly designates the referenced artifact as part of the stable agreement; neither `status.md` nor `log.md` may be the sole source of what “done” means. Without a finish line the relay runs forever — this is non-negotiable.
-- **Sizing.** How much is *one leg*? This is project- and plan-specific; the charter defines it (a task, a slice, a time/scope budget — whatever fits). The skill does not decide this for you.
-- **Task selection policy.** How a runner chooses the next task when `status.md` does not name one explicitly.
-- **Handover.** How a runner hands off: what the spawn prompt should say and what the next runner must read. A normal handoff starts with a natural header containing the relay name and next leg identifier, then points at `charter.md` and `status.md`, not the full log.
-- **Intervention signal.** When and how a runner must stop and get the human, and how that is made visible. The charter defines relay-specific triggers and signaling. A runner who would need to change the agreed finish line without explicit human direction must always stop and raise that signal.
-- **Reading discipline.** The files a runner should read to orient, and any files that should not be read defensively.
+Keep this destination-focused. Do not turn it into an implementation plan, technical design, quality checklist, risk inventory, or copy of project instructions. Those details anchor later runners to route assumptions and blur what requires human agreement.
 
-The charter *can* be edited. Clarifications and maintenance are fine, but changing the goal, finish line, or a supporting artifact that the charter designates as part of them changes the relay's agreement; it is not ordinary leg-level adaptation. Runners adapt the route, not the destination. Make such a change only with explicit human agreement, record it in `log.md`, and update the charter before continuing. If you believe the change is needed and do not already have that agreement, stop and raise the intervention signal. Frequent charter edits are still a smell that the design is unsettled.
+### Current baton
 
-**Status** (`status.md`) — the compact baton/current state. This is the file every runner reads after the charter, and every runner updates before handoff or stop. Keep it short enough that a fresh runner can load it cheaply.
+Defines present position, the last completed and next leg identifiers, current or next task, targeted context pointers, blockers, and required progress updates. It stays compact. It carries position, not destination.
 
-The baton carries position, not destination. `status.md` is authoritative for current state and next-leg selection only. It may describe a leg task or point to relevant context, but it must fit the charter's finish line and must not redefine, narrow, or extend it. Information needed to judge whether the relay itself is complete needs a stable home in the charter or a supporting artifact the charter designates; status points there rather than becoming its replacement.
+### History
 
-It should answer:
+Preserves concise append-only evidence of completed legs, decisions, artifacts, agreement changes, and stops. It supports targeted lookup and auditability; it is not the default orientation surface.
 
-- **Current position.** Where the relay is now.
-- **Current or next task.** The next leg if known; otherwise enough information to apply the charter's task selection policy.
-- **Leg tracking.** The last completed leg and the next leg to run. Keep this explicit so runners do not have to infer whether “current leg” means the leg just finished or the leg being handed off, and so the handoff prompt can identify the next leg accurately.
-- **Relevant context.** Only the files, sections, commands, artifacts, or specific log entries needed for the next leg.
-- **Progress documentation.** Where and how this runner must make progress durable: update `status.md`, append `log.md`, update artifacts, or follow another workflow named by the charter.
-- **Blockers / intervention state.** Current risks, open decisions, or active reasons to stop.
+Separating these roles prevents recency from becoming authority. A newer baton cannot silently override the stable agreement, and a large history does not become mandatory context.
 
-Leg identifiers distinguish handoffs; they do not predict a fixed route or total number of legs.
+## Operational profiles
 
-Think of `status.md` as the thing passed from runner to runner. If it grows into a history dump, compress it back into current state plus pointers. If finish-line-defining content has crept into status without a stable home, restore it to the charter or a charter-designated artifact before compressing it away. If an older relay lacks leg tracking, repair it when you update status; prefer the leg identifier from the prompt or status, and do not read `log.md` end-to-end just to reconstruct prior identifiers.
+This base skill is intentionally non-operational and tool agnostic. It does not choose:
 
-**Log** (`log.md`) — append-only history. Each leg appends a concise entry recording what it did, decisions made and why, durable artifacts changed, status updates made, and blockers. The log preserves auditability, including agreed changes to the charter, but it is **not** orientation memory and does not replace the charter as the current agreement.
+- how a successor context is created;
+- where or in what format durable state lives;
+- how large a leg should be or how tasks are selected;
+- whether work uses source control, worktrees, commits, tests, reviews, or delivery gates;
+- how intervention reaches a human; or
+- what project-specific quality standard applies.
 
-Do not read `log.md` end-to-end by default. Read targeted log entries only when `status.md` points to them, when the charter requires a specific lookup, or when there is an inconsistency you must resolve before continuing.
+An operational profile supplies those bindings and decides where to keep its identity and any operational record. Each handoff makes the active profile visible to the fresh runner. A profile may be strongly opinionated without putting its mechanics into the destination agreement or turning its choices into the definition of Relay.
 
-Optional files such as `plan.md`, `backlog.md`, specifications, or artifact notes are fine, but runners should read them only when the charter/status points to the relevant part. If the charter designates one as part of the finish line, changing that part follows the same agreement rule as changing the charter itself.
+Projects can layer any operational profile that fits their environment while preserving the invariants above.
 
-## Context containment rule
+## Context containment
 
-A runner normally reads:
+A fresh runner normally needs only:
 
-1. `charter.md`
-2. `status.md`
-3. Only the specific files or log entries referenced for the current leg
+1. the stable agreement;
+2. the current baton; and
+3. the specific supporting material those surfaces identify for the leg.
 
-Do not defensively rebuild the relay's full history. Do not read the full log, the full backlog, or a large artifact tree just because they exist. The relay stays scalable because each runner pays only for the context needed now.
+A baton that routinely requires full-history or whole-artifact-tree reconstruction violates bounded orientation. A state gap that can be resolved only through broad archaeology or guessing about the destination is an intervention condition, not ordinary continuation.
 
-If `status.md` is insufficient, fix the baton rather than compensating by reading everything. Here, fixing means restoring an accurate account of current state, tasks, and pointers within the charter's bounds; it does not mean reconstructing or revising the finish line in status. Use targeted inspection to clarify the current state, update `status.md` so the next runner has a clean start, and continue only if the task is still clear. If resolving the gap would require broad archaeology or judgment about past intent or what “done” should mean, stop and raise the intervention signal.
+## Failure smells
 
-## Running one leg
+- **Coordinator creep:** a persistent supervisor plans, watches, or approves every leg.
+- **Role bureaucracy:** fixed agent roles or layer ownership replace fluid, outcome-driven slices without a real constraint requiring them.
+- **No stable finish line:** mutable current state is the only definition of done.
+- **Baton authority creep:** status quietly narrows or expands the agreement.
+- **Context leakage:** every runner reloads the full history or inherits an unbounded conversation.
+- **Eager or parallel handoff:** successors begin before the current leg is durable, or one runner fans out the chain.
+- **Oversized legs:** a runner continues beyond a coherent context-contained checkpoint.
+- **Silent stall:** work stops without durable blocker or intervention state.
 
-This is the loop you run when you are dispatched into a relay.
-
-1. **Orient from the packet.** Read `charter.md` and `status.md`. Confirm from the charter the relay identity/root, finish line, sizing, task-selection policy, handoff protocol, intervention signal, and reading discipline. Confirm from status the current position, last completed leg, next leg to run, current/next task, and blockers. If you are not sure whether a Relay is active, the dispatch prompt or packet must establish it; loading this skill alone does not.
-2. **Choose the leg.** Prefer the explicit current/next task in `status.md`, provided it serves the charter's finish line and fits its sizing. If none is named, apply the charter's task selection policy. If that still requires context, inspect only the referenced plan/backlog/artifact sections. Do not adopt a task merely because status is newer. If the next task is still ambiguous, falls outside the charter's bounds, or would require moving the finish line, stop and involve the human.
-3. **Re-anchor to the charter.** Does the chosen leg still serve the finish line, and does reality still permit it? Adapting how to get there is your job. If reality indicates that what “done” means should change, stop and raise the intervention signal rather than quietly redefining it.
-4. **Run one leg.** Do exactly one well-sized slice, per the charter's sizing. Resist doing "just a bit more" — extra scope bloats context and breaks the containment that makes Relay work.
-5. **Document progress.** Make all work durable. Update `status.md` with the new current state, last completed leg, next leg to run (if any), next task or task-selection pointer, relevant context for the next runner, and blockers. Append a concise `log.md` entry with what you did, why, decisions made, artifacts changed, and whether you are handing off or stopping.
-6. **Decide: hand off, or stop.**
-   - **Hand off** if there is a clear next leg and you are on track. Use `spawn_session` once, with a prompt whose first line is a natural task header containing the relay name and next leg identifier (for example, `Relay "<name>" leg <identifier> begins now.`), followed by the Relay method and pointers to `charter.md` and `status.md` (so this skill loads and they can orient cheaply). Then you are done. Handoff is deliberately fire-and-forget: `spawn_session` starts an independent session you will not see and cannot steer — do not reach for a tracked subsession to keep an eye on it. Letting go is the point. The next runner is trusted to run their own leg, and the relay packet is the only thread between you; if you feel the need to watch downstream work, that usually means the leg wasn't sized or handed off cleanly, or an intervention signal should have fired.
-   - **Stop — do not spawn —** if the goal is reached, or you are blocked, or the charter's intervention signal fires. Update `status.md`, append a clear note in `log.md`, and raise the intervention signal so the watching human sees exactly what happened and what they need to decide. A stalled relay that stopped cleanly with a clear blocker is a success; a relay that spawned a confused next runner is a failure.
-
-A good handoff prompt is short and explicit. The example below uses the default packet root; substitute the root recorded in the charter when it differs. Put the relay identity and leg identifier at the very beginning so the handoff is immediately distinguishable:
-
-```text
-Relay "<name>" leg <identifier> begins now.
-
-You are the next runner in this Relay method chain.
-
-Read:
-- .pi-web/relays/<name>/charter.md
-- .pi-web/relays/<name>/status.md
-
-Do not read log.md end-to-end. Use it only for targeted lookup if status.md or charter.md points you there.
-
-Run one leg according to the charter. Before handing off, update status.md, append log.md, make work durable, then either spawn the next leg once or stop with a clear intervention note.
-```
-
-## Planning a relay
-
-When the user asks to set up a relay, your job is to produce the relay packet: `charter.md`, `status.md`, and `log.md`. The charter must have the required slots filled: relay identity, goal, sizing, task selection policy, handover, intervention signal, and reading discipline. Before dispatch, preserve the agreed finish line and the stable boundaries needed to judge it in the charter or in supporting material the charter explicitly designates. Do not make the initial status or planning conversation the only place those requirements exist. The initial status must give the first runner a compact baton: current position, leg tracking (for a numeric scheme, usually last completed leg 0 and next leg to run 1 for a new relay), first task or task selection pointer, relevant context, documentation expectations, and known blockers. The log may start empty or with a short seed entry explaining that the relay was created.
-
-Unless the user or dispatching instructions provide these choices or a rule for deriving them, draw them out from the user rather than inventing them: ask what the finish line is, how much should be one leg, how runners pick tasks, how runners hand off, what they should read, and when they must stop and get the human. Sizing, task selection, and the intervention signal especially are not for the generic method to decide — propose options if it helps, but do not quietly settle them yourself.
-
-Do **not** invent what a "good" plan, leg size, or cadence looks like when no policy is supplied — those choices are deeply project-, plan-, and human-specific. Explicit user, project, or dispatch instructions may provide defaults; follow them rather than replacing them with the skill's preferences. Your value in planning is making sure the relay is *runnable*: the finish line exists, sizing is stated, task selection is stated, handover is stated, reading discipline is stated, and the intervention signal is stated. Once the packet is agreed, you can dispatch the first leg with `spawn_session`.
-
-## Smells to watch for
-
-- **No stable finish line** → infinite or self-redefining relay. Refuse to run when “done” exists only in mutable state.
-- **Goal drift / baton authority creep** → a leg or `status.md` quietly restates, narrows, or extends what the relay is for. Re-anchor to the charter; changing the destination requires human agreement.
-- **Charter churn** → stable policy changes every leg. The design isn't settled; involve the human.
-- **Status bloat** → `status.md` turns into a history dump. Compress it to current state plus targeted pointers.
-- **Defensive reading** → reading the full log/backlog/artifact tree to feel safe. Use the packet and targeted lookups; stop if the baton is not enough.
-- **Eager spawning** → spawning early, spawning several runners, or spawning before work is durable. One leg, at most one handoff, at the end.
-- **Silent stall** → getting stuck and stopping with no note, or spawning anyway. Always update status, log the blocker, and surface it.
+Operational details may vary widely. These failures matter because they undermine the principle, not because a particular tool or file convention was violated.