Handoff execute

/handoff-execute

Receive a handoff brief in a fresh agent session and execute it end-to-end with a source-ingestion gate before planning, source-cited plan steps, acceptance-verified output, and a ground-truth retro. This is the receiving-side counterpart to /handoff — /handoff writes the brief, /handoff-execute enforces the discipline that turns the brief into ground-truth work.

Structured execution spec: protocol.yon. Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the @STAMP date.

Boundary

Use handoff-execute to consume a handoff brief produced by /handoff (YAML frontmatter type: handoff + YON body blocks). Do not use it for:

• PLAN.md or implementation_plan.md — use /plan-execute (different schema, no @SOURCES block, no retro requirement).
• A formal post-execution self-gate — use /verify (requires intent/plan/execution artifacts; checks for drift).
• Independent outside-agent review of completed work — use /cold-review (reviews, doesn't execute).
• Re-verifying one specific claim — use /double-check.

handoff-execute is the only skill that consumes a handoff brief and produces the canonical retro file.

Invocation

/handoff-execute "<absolute-path-to-brief>"

The brief path is required. Always quote the path — Windows vault paths may contain spaces.

Force flag — /handoff-execute --force "<path>" downgrades the Phase 2 gate from ABORT to WARN, allowing execution to proceed even when one or more @SOURCES.required entries fail to read. Intended for async cases where the brief author isn't reachable to amend the brief; surfaced explicitly so it can't be invoked accidentally. The blocked retro is still written for audit.

Vault path dependency — Phase 5 writes the retro to $VAULT/Handoffs/{project}/retros/... (set $VAULT to your vault root). This path is inherited from /handoff. If $VAULT is unset or the host has no Obsidian vault, the cold agent must override the retro write target via the brief's output_location field, or the write will fail and the skill will fall back to chat-only retro emission with a @WRITE_FAILURE block (see Phase 5).

Execution

Five ordered phases, two hard ABORT gates (Phase 2 source-ingestion and Phase 2 premise pre-flight, both in gated mode without --force) and three WARN gates (advisory-mode banner, Phase 3 source citation, Phase 3 acceptance coverage).

Phase 1 — Brief ingest

Read the brief file in full. Parse YAML frontmatter; validate type: handoff. Locate the YON blocks in the body:

• @TASK — task description + scope paths + evidence pointer
• @OUTCOME — acceptance sentence + verify commands
• @SCOPE (if present) — forbidden actions + time budget
• @SOURCES (if present) — required and optional source tiers
• @GROUND_TRUTH_REQUIRED — retro discipline declaration
• Profile-specific blocks: @SUBTASKS (orchestrator), @CONTINUATION (new-session)

Emit a one-line confirmation: Brief loaded: <slug> · profile=<p> · required-sources=<N>.

Phase 2 — Source ingestion (two modes)

Mode is determined by what the brief declares:

• Gated mode — brief has @SOURCES.required, OR legacy @SCOPE.must_read, OR an explicit markdown heading matching Read-first / Read these first / locked inputs (a real heading line — not the phrase inside a fenced example). For the markdown case, the required tier = the numbered/bulleted lines under that heading bearing a path or [[wikilink]] (lines tagged (optional) go to the optional tier). Enumerate the required tier, read each entry fully via the runtime's read tool, gate planning on completion. Hybrid severity for the markdown case: ≥1 cleanly-enumerable entry → gated (ABORT-on-fail); a prose-only section with no enumerable entries → downgrade to WARN (can't gate on nothing). (Many hand-authored briefs declare locked inputs this way rather than as a YON block; the gate still fires. The durable producer-side fix is for the brief author to emit @SOURCES.required / author via /handoff, which already does so — this markdown path is the consumer-side safety net for hand-authored + legacy briefs.)

• Advisory mode — brief has none of the above. Scan the brief body for explicit references ([[wikilinks]], absolute paths), read them best-effort, emit a prominent warning, proceed to planning regardless:

  ⚠ ADVISORY MODE: brief did not declare @SOURCES; no source-read gate enforced. Recommend amending the brief to add @SOURCES.required.

In both modes, emit a checklist:

Source ingestion:
  [✓] /c/Projects/x/y.ts                              (read, 142 lines)
  [✓] [[Skills/frontmatter-schema]] → c:/...md        (read, 89 lines)
  [✗] /c/Projects/x/missing.ts                        (NOT FOUND)

Gate (gated mode, no --force): if any required source fails to read, halt and write a verdict: blocked retro with a @SOURCE_FAILURES block listing what couldn't be loaded plus a @RESUME_HINT block telling the originating session exactly what brief amendment is needed. Do not proceed to planning. Surface a one-line recovery prompt to the cold agent's runtime user:

Source ingestion failed in gated mode. Either amend the brief and re-invoke, or re-invoke with --force to proceed in degraded mode: /handoff-execute --force "<path>".

Gate (gated mode, --force in effect): same failure list emitted, but the skill proceeds to Phase 3 with a degraded mode (--force) banner. The retro records @SOURCE_FAILURES even though execution continued.

Gate (advisory mode): the same failure downgrades to WARN — emit the failure list but continue.

Did-you-mean hint: on a [✗] failure, run a basename search across the parent project and the vault, and surface the top candidate as a non-actionable suggestion: Source not found: foo.ts. Did you mean: /c/Projects/x/foo.ts? Do not auto-resolve.

Drift warning: for each successfully-read @SOURCES.required entry, compare its mtime to the brief's created: frontmatter date. The frontmatter has day-granularity; the mtime has second-granularity. Apply a 24-hour tolerance: only warn if the source mtime is more than 24 hours after midnight of brief.created. Format: Source drifted since brief was written: <path> (modified <duration> after brief.created).

Premise pre-flight (all profiles, gated as a hard ABORT). A stale brief can describe a world that no longer exists — the work may already be shipped, the named structure may have changed, or the test baseline may have moved since the brief was written. Path existence is already checked above; this gate checks the brief's premises. Before emitting any plan, reconcile each against the live repo:

• Git state — "is this already done?" Run git log / git status over the brief's scope paths. If commits matching the brief's task (by message, by the set of touched files, or by an explicit SHA the brief names) have already landed, the work may be done or partially done. This is the strongest drift signal — halt rather than re-doing landed work.
• Cited baselines. If the brief states a concrete number (463 tests, schema v15, 90 plugin ops), check it against the current tree. A mismatch means the brief's baseline drifted — surface the stated-vs-actual delta.
• Structural claims. Verify the brief's structural assumptions still hold beyond per-source existence — a package it says to create doesn't already exist; a file it says is missing is actually missing.

Emit a premise checklist (stated → actual per premise). If any premise is stale, halt and write a verdict: blocked retro with a @PREMISE_DRIFT block (each drifted premise: stated vs. actual) plus a @RESUME_HINT telling the originating session what to amend. Distinguish already-shipped (brief is obsolete — stop) from baseline-drift (surface and let the runtime user decide). --force downgrades premise drift to WARN, identical to the source-ingestion gate.

This is the general-profile counterpart to the diagnosis-mode reproduction-first rule (Phase 4): a diagnosis brief verifies its failure still reproduces; every brief verifies its premises still hold.

Verify-command resolvability (WARN, side-effect-free). A brief can name a verify or spot-check command that no longer resolves — most commonly the wrong binary/CLI path. Before emitting any plan, statically reconcile each command in the brief's verify: frontmatter (and any "regenerate-and-grep" / spot-check command in the body) against the live repo: confirm the named binary/dist path exists, and that a CLI subcommand resolves (a side-effect-free --help probe is allowed; never run the full verify command here — it may mutate). On an unknown command / no such file / command not found resolution failure, emit a WARN with a "did you mean?" hint (basename/sibling search) and surface the corrected command so Phase 5 runs the right one — do not abort: the brief's task is still executable; only its verify command is mis-pathed. (Added after V-DOC-1: the brief's spot-check named packages/lyt-vault/dist/cli.js agent-manual, but that verb is registered only in the meta CLI packages/lyt/dist/cli.js — the standalone lyt-vault CLI errors unknown command 'agent-manual'. The mismatch only surfaced at execution, and a cold reviewer independently re-derived it — two signals for the same Phase-2 gap.)

@SOURCES.optional entries are surfaced in the checklist (so the cold agent knows they exist) but not read in this phase. They are read on-demand in Phase 4 if a plan step calls for them.

Phase 3 — Plan

Produce a numbered plan that maps each step to (a) the acceptance sub-criterion it addresses and (b) the source(s) supporting it (file:line where possible):

1. <action>  →  acceptance: <fragment>  ·  source: /c/Projects/x/y.ts:42
2. <action>  →  acceptance: <fragment>  ·  source: [[Skills/...]]:section

Gate (WARN): every plan step SHOULD cite at least one source. Uncited steps are flagged for the cold agent's review but don't abort — some steps are pure tooling/setup.

Gate (WARN — coverage): @OUTCOME.acceptance is a single sentence; the cold agent reasons over its clauses and flags any clause not addressed by at least one plan step. The flag is surfaced for caller review but does not abort — the cold agent's clause parsing is fallible, and a false gap shouldn't block useful work. If a real gap exists, the cold agent must say so explicitly in the plan emission ("clause X not addressed because Y") rather than emit a silent gap. For more rigorous coverage checking, brief authors can rewrite acceptance as semicolon-delimited clauses so the cold agent has explicit segmentation to reason against.

Phase 4 — Execute

Run each plan step in order. On-demand @SOURCES.optional reads are citation-driven, not agent-judgment — a step triggers a load only if it names a @SOURCES.optional entry in its · source: citation from Phase 3. The cold agent does not decide ad-hoc to read optional sources outside the plan; if mid-execution it discovers, on its own judgment, that it needs a source not named anywhere in the brief, it halts and surfaces the gap rather than silently expanding scope. This does not cover two narrower cases: a target file the brief's own body prose already names with a file:line citation (open it when the citing plan step executes; note the read in @DELTA_FROM_BRIEF), or the brief's prose referencing a fact/decision by name without citing where it lives (read the minimal file needed to resolve the literal reference; flag as a citation gap in @DELTA_FROM_BRIEF). Read the specific cited section (not the whole file). Capture for each step: artifacts modified, command outputs, hashes of changed files.

Diagnosis-mode briefs (mode: diagnosis in frontmatter) — reproduction-first rule. If the brief names specific files as "affected" by a flake/bug, treat the list as a hypothesis, not ground truth. Before applying fixes, reproduce the named failure mode and verify each listed file is actually involved. Briefs carry forward stale bisects from prior phases; the actually-affected file set may differ (new file flake-prone, listed file unrelated). Surface any divergence in @DELTA_FROM_BRIEF before declaring the fix complete.

Coupled-constant edits. If the plan involves touching a constant whose value is duplicated across multiple files (retry budgets, timeouts, page sizes, magic numbers, feature flags), invoke /audit-coupled-constant as part of this phase — author-maintained SEE ALSO comments are documentation, not enforcement, and one missed site means the trail silently lies.

If a step fails, do not silently retry — emit a partial retro (verdict: partial) listing what was completed, what failed, and why.

Phase 5 — Verify + retro

Run every command in @OUTCOME.verify (the brief's frontmatter verify: field). Compare results to the acceptance sentence.

Gate-suite + per-clause mapping. If the work produced committable code, also run the project's defined gate suite (lint / test / typecheck — whatever the project declares; e.g. turbo run lint test typecheck where present) before declaring done — this is the deliberate pre-commit gate, not a speculative auto-run. Then map each acceptance clause to the specific verification that exercised it, and report the result explicitly in the retro as a @GATE_STATUS block: per clause → verified | unverified | failed, plus the gate-suite outcome (pass | fail | skipped — <why>). An unverified clause or a skipped gate is allowed but must be named, not silently omitted — a clean-looking retro with an unstated coverage hole is the failure this prevents.

Write the retro to:

$VAULT/Handoffs/{project}/retros/{date}-{slug}-retro.md

(Or the brief's output_location override if present. See Invocation → Vault path dependency.)

The retro frontmatter and body schema is canonical in handoff/SKILL.md "Retro schema". Mandatory YON blocks: @OUTCOME_DELIVERED, @GROUND_TRUTH (with artifacts_modified paths+hashes and git_diff_summary), @GATE_STATUS (per-clause verified|unverified|failed + gate-suite outcome), @DELTA_FROM_BRIEF, @RECOMMENDATIONS, @VERDICT. Narrative-only retros are rejected at write time.

Also emit the retro as a chat block — full content if <500 lines, otherwise a summary + path — so the originating session can paste it back for second-assessment.

Write-failure handling. If the vault write fails (path missing, permission denied, broken wikilink rendering, disk full): emit the retro to chat regardless, append a @WRITE_FAILURE block=true | reason="..." | attempted_path="..." block to the chat-rendered retro, and set the final @VERDICT to partial (even if execution itself was clean). Do NOT silently exit and do NOT retry — the cold agent's runtime user can paste the chat-emitted retro into the originating session for manual filing.

Plan-artifact housekeeping. If a plan artifact was written in Phase 3 (per project Work Management protocol — typical for <vault>/Projects/<project>/work/{date}-plan-{slug}.md), update its frontmatter at session close: set status: to done (or partial / blocked matching the retro's @VERDICT), and add a commits: list naming the SHA(s) that closed the plan. This honors the project's cross-reference rule (vault work/ files reference commit SHAs; code commits reference the work slug in the body). Trivial edit, but easily forgotten if the cold agent skips it — the originating session ends up with a stale in-progress plan artifact that misrepresents project state.

Rules

• MUST read all @SOURCES.required entries fully before emitting any plan text (gated mode).
• MUST run the premise pre-flight (git state for already-shipped work, cited test/schema baselines, structural claims) before emitting any plan, and halt with a @PREMISE_DRIFT verdict: blocked retro if the work is already shipped or a baseline premise is stale. Downgraded to WARN under --force.
• SHOULD statically reconcile the brief's stated verify: / spot-check commands against the repo before planning (named path exists; CLI subcommand resolves via a side-effect-free --help probe — never run the full verify here). WARN + surface a corrected command on an unknown command / no such file mismatch; do not abort (the task is still executable; only the verify command is mis-pathed).
• MUST write the retro with @GROUND_TRUTH (paths + hashes + git diff). Narrative-only retros are rejected.
• MUST halt and write a verdict: blocked retro if a @SOURCES.required entry fails to read in gated mode and --force is not set. With --force, proceed in degraded mode and record the failure list in the retro instead.
• MUST emit retro to chat with a @WRITE_FAILURE block and set @VERDICT to partial if the vault write fails. Do not silently exit; do not retry.
• SHOULD cite at least one source per plan step.
• SHOULD reason over @OUTCOME.acceptance clauses and flag any clause not addressed by ≥1 plan step (WARN — single-sentence acceptance has fallible clause segmentation; flag explicitly rather than abort).
• SHOULD run the project's defined gate suite before declaring done when the work is committable code, and record @GATE_STATUS in the retro: each acceptance clause → verified | unverified | failed, plus the gate-suite outcome. Skipped gates and unverified clauses are allowed but must be named, never silently omitted.
• SHOULD read the specific cited section of a @SOURCES.optional entry on-demand only when a plan step's · source: citation names it. Loads are citation-driven, not agent-judgment.
• MUST NOT silently retry failed steps. Emit a partial retro instead.
• MUST NOT silently expand scope if mid-execution the agent, on its own judgment, decides it needs a source not named anywhere in the brief. Halt and surface the gap; the brief must be amended. (Does not cover: a brief-cited file:line edit target absent from @SOURCES, or resolving an unlinked named reference in the brief's prose — both are read on-demand and noted in @DELTA_FROM_BRIEF, not halted on.)
• MUST NOT invent sources not present in the brief. If a needed source is missing, halt and request brief amendment.
• MUST NOT auto-resolve a missing @SOURCES.required entry by picking the closest filename match. Surface the suggestion only.

Anti-patterns

• Starting to plan before Phase 2 completes — defeats the entire purpose of the skill.
• Planning straight from the brief without reconciling its premises — you risk re-doing already-shipped work or building against a baseline that drifted since the brief was written.
• Reading @SOURCES.required skim-only — count of files read ≠ comprehension. If a source is too long to read fully, push back: brief author should split it into a smaller required tier + larger optional tier.
• Treating advisory-mode warnings as cosmetic — they signal that the brief is under-specified. Ask the originating session to add @SOURCES.
• Writing the retro to chat only, skipping the canonical vault file — the file is the ground-truth artifact.
• Auto-resolving a missing source by picking the closest filename match — surface the suggestion, do not act on it.

Human output. This skill's handler-facing output obeys the human-output contract (human-output/SKILL.md).

Next skills. On completion, run the Next Skills protocol (next-skills/SKILL.md): surface the next-skills recommendations from front-matter for the caller to pick. Offer only — never auto-invoke.

Self-improvement. On completion, run the Self-Improvement Protocol (self-improve/SKILL.md): if this run surfaced a concrete, blocking-or-recurring weakness in this skill, propose a specific fix for the handler to approve. Conservative — silent otherwise. Never auto-apply.