@hassangameryt/freeflow 0.3.0 → 0.5.0

package/skills/execute-work/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: execute-work
+description: Use when executing or resuming implementation, fixes, prototypes, documentation updates, repository maintenance, or other concrete changes.
+---
+
+# Execute Work
+
+Carry out concrete work through bounded actions and fresh evidence only when it was requested or approved and the effective mode permits mutation.
+
+A **slice** is one coherent result tracked and reviewed as a unit. A **bounded action** is one implementation, experiment, correction, or observation inside that slice. One slice may span multiple Feedback Loop iterations and owning skills while its intended result remains coherent.
+
+Read [the execution loop](references/execution-loop.md) when work spans multiple actions or slices, resumes from prior state, needs a specialized method, reaches a checkpoint, or reveals follow-on work.
+
+## Follow The Execution Route
+
+Use this as a directed map, not a fixed phase sequence:
+
+```text
+[Requested or approved concrete work; effective mode permits mutation]
+-> [Orient and establish the current slice]
+-> [Take one bounded action]
+-> [Test or observe]
+-> [Verify what the evidence proves]
+   -> clear local defect -> correct -> test or observe again
+   -> unclear, repeated, or route-changing result -> Workflow
+   -> supported -> silent self-review -> freeze
+-> [Route]
+   -> more accepted work in this slice -> next bounded action
+   -> coherent boundary extension -> approve and record when needed -> next action
+   -> distinct result, authority, or evidence boundary -> Workflow
+   -> approved checkpoint due -> owning skill -> route again
+   -> supported exit -> report
+```
+
+Implementation beginning does not justify continuation. Continue only while authority, evidence, and the current slice remain coherent.
+
+## Orient Before Changing State
+
+Establish:
+
+- intended result and the source that supports it;
+- current slice, accepted scope, and relevant live state;
+- direct check or observation that can disagree with the result;
+- stop conditions, due checkpoints, and authority boundaries.
+
+A clear user request can be enough. A small self-contained change needs no Spec, Plan, or Working Record merely because execution was selected.
+
+Inspect relevant code, tests, docs, policies, artifacts, repository state, and current external constraints before relying on memory. When sources materially conflict or the intended result is unsafe to infer, return the evidence to [Workflow](../workflow/SKILL.md) rather than choosing silently.
+
+When a Working Record exists, use [Track Work](../track-work/SKILL.md) for write-ahead slice state and later reconciliation. Announce the active slice once in a compact line when useful; do not announce every action or manufacture an identifier for a tiny task.
+
+## Bound Each Action
+
+Choose the smallest coherent action that can produce the intended result or useful evidence:
+
+- keep unrelated and later work outside it;
+- choose reversible local details from repository conventions;
+- let an experiment fail safely and preserve its discard, revise, or promote condition;
+- use only specialized methods and domain guidance that the concrete boundary needs.
+
+When an accepted behavior change, bug correction with a supported cause, consequential rule, or behavior-preserving refactor benefits from a failing check first, use [TDD](../tdd/SKILL.md) for that bounded action before changing production behavior.
+
+Before work changes the intended result, scope, authority, evidence boundary, or stop conditions, decide through Workflow whether it is an accepted extension or a new slice. When a Working Record exists, use Track Work to record an accepted extension before executing it. Do not let a series of “small” additions silently replace the original result.
+
+## Execute For The Required Boundary
+
+Match implementation and evidence to the work. Code may need behavior tests or runtime observations. Documentation, configuration, generated artifacts, and repository maintenance may need parsing, links, builds, diffs, structural checks, or installed-artifact evidence.
+
+Do not rewrite tests, checks, Specs, Plans, policies, or accepted behavior merely to make implementation pass. Determine whether the implementation, evidence, environment, or source is wrong before changing what defines success.
+
+When writing or changing code, read [Code Practices](references/code-practices.md). Prefer clear ownership, names, and failure behavior. Comment only non-obvious rationale, constraints, invariants, or temporary behavior with a real exit condition.
+
+Handle an edge case only when accepted behavior, observed evidence, or material safety requires it. If expected behavior is undefined and would change observable behavior or scope, return it to Workflow. When related patches keep adding states, flags, or caller coordination, stop and return the shared pressure rather than extending the patch stream.
+
+## Close Each Evidence Iteration
+
+After each meaningful bounded action:
+
+1. run the focused tests or observations appropriate to its claim;
+2. use [Verify Work](../verify-work/SKILL.md) when the claim or observing boundary needs its fuller method;
+3. when supported, use [Review Work](../review-work/SKILL.md) for silent self-review;
+4. correct clear local issues within existing authority and re-verify;
+5. freeze the supported state and return route-changing evidence to Workflow.
+
+A failed or inconclusive check does not prove the design or source is wrong. Correct a clear local defect; use [Diagnose Failure](../diagnose-failure/SKILL.md) when the cause is unclear or failure repeats.
+
+Further polish, advisory warnings, unrelated issues, and review findings without mutation authority are feedback to classify, not permission to keep editing.
+
+## Route Continuation Deliberately
+
+Continue inside the current slice when the next bounded action is accepted, its intended result remains coherent, the combined boundary can still be verified as one unit, no stop condition applies, and no checkpoint is due.
+
+Before a distinct result begins, let Workflow establish the current slice outcome, then use Track Work when present to select the next authorized slice. A route through discussion, diagnosis, review, verification, or an approved checkpoint does not itself end or replace the current slice.
+
+A Plan preserves intended strategy, not progress. Return material changes to its order, mechanism, dependencies, slices, or checks to Workflow. Do not add public documentation, migration, deprecation, push, integration, release, launch, or another separately controlled action without its own authority.
+
+## Report The Supported State
+
+Report the accepted result, fresh verification evidence and limits, material route changes, current slice or artifact state, and unresolved or unverified work. A supported action is not automatically a completed slice, and a completed slice does not authorize the next one.

package/skills/execute-work/references/code-practices.md

@@ -0,0 +1,78 @@
+# Code Practices
+
+Read this when an Execute Work slice writes or changes code. Follow the repository's language, style, testing, and documentation conventions before generic advice.
+
+## Make Intent Legible
+
+- Use names that express domain meaning rather than implementation trivia.
+- Keep behavior, state, and policy near the code that owns them.
+- Prefer the smallest coherent change over speculative abstraction or broad cleanup.
+- Make important invariants and failure behavior explicit in code, types, tests, or narrow comments.
+- Add a dependency, fallback, flag, state, or extension point only for accepted behavior or observed pressure.
+
+Clear code explains what happens. Comments preserve important context the code cannot express safely.
+
+## Comment Non-Obvious Why
+
+Comment when a future reader could reasonably make a harmful change without knowing:
+
+- an invariant, ordering, concurrency, precision, security, or compatibility constraint;
+- why an apparently simpler approach is wrong;
+- an external limitation or deliberate workaround;
+- why an obvious alternative was rejected;
+- why temporary behavior exists and what permits its removal.
+
+Do not:
+
+- narrate clear statements or control flow;
+- preserve comments that no longer match the code;
+- record broad architecture history inline;
+- write `TODO: fix later` without a real reason or exit condition.
+
+Put task status and future work in the Working Record or issue tracker. Put broad durable rationale in a Spec, decision record, or ADR. Leave only the local explanation needed to change the code safely.
+
+```ts
+// Bad: repeats the code.
+count += 1; // Increment count
+
+// Good: explains a non-obvious constraint.
+// Keep two passes: pass 2 consumes offsets frozen by pass 1.
+runFirstPass();
+runSecondPass();
+```
+
+For temporary behavior, name the actual constraint and removal condition. Link an existing issue when one exists; do not invent tracking metadata.
+
+## Handle Edge Cases By Evidence
+
+Before adding behavior for an edge case, ask:
+
+1. Is it required by accepted behavior or a settled failure contract?
+2. Has it been observed or shown reachable at the supported boundary?
+3. Could ignoring it cause material safety, data, security, compatibility, or user harm?
+4. Is the expected result defined and inside the accepted work?
+
+Then act proportionately:
+
+- **Required or observed, with defined behavior:** implement the smallest complete behavior and test the relevant boundary.
+- **Material but undefined:** stop and return the missing behavior decision to Workflow.
+- **Plausible but unsupported:** gather evidence; do not add speculative handling.
+- **Useful but optional:** report or defer it as separate work.
+- **Purely hypothetical:** leave it alone.
+
+```text
+API contract permits a missing value and defines the result
+-> implement and test it
+
+"What if this is null?" with no requirement or reachable path
+-> do not add a null branch; classify the concern first
+
+Each correction reveals another related state or flag
+-> stop patching; diagnose the shared contract, cause, or ownership
+```
+
+Prefer an explicit invariant or clear failure over invented retry, fallback, recovery, or compatibility behavior. Handling an edge case creates a contract and future maintenance cost.
+
+## Stop When The Slice Is Supported
+
+Once the accepted result is supported, comments are accurate, and no material self-review issue remains, stop. Possible polish, unrelated cleanup, and imagined resilience are not unfinished work. They require new evidence or another selected slice.

package/skills/execute-work/references/execution-loop.md

@@ -0,0 +1,77 @@
+# Execute Work Loop
+
+Read this when execution spans multiple bounded actions or slices, resumes from prior state, needs a specialized method, reaches a selected checkpoint, or reveals follow-on work. [Execute Work](../SKILL.md) owns the normal method; this reference expands its directed routes.
+
+## Directed Execution Graph
+
+```text
+[Requested or approved concrete work; effective mode permits mutation]
+-> [Orient]
+   source + authority + live state + current slice + stop conditions
+-> [Choose one bounded action]
+-> [Load one needed method or reference]
+-> [Execute]
+-> [Test or observe]
+-> [Verify the claim at its required boundary]
+   -> clear local defect
+      -> [Correct within authority]
+      -> [Test or observe]
+   -> unclear or repeated failure
+      -> [Diagnose Failure]
+      -> [Workflow routes from the cause]
+   -> contradicted, inconclusive, or route-changing evidence
+      -> [Workflow]
+   -> supported
+      -> [Silent self-review]
+      -> [Correct clear local issue and re-verify, or freeze]
+-> [Route from the supported state]
+   -> more accepted work for the same coherent result
+      -> [Choose the next bounded action]
+   -> accepted extension to result / scope / authority / evidence / stop conditions
+      -> [Record write-ahead when a Working Record exists]
+      -> [Choose the next bounded action]
+   -> distinct result, authority, or independently useful evidence boundary
+      -> [Workflow establishes current slice outcome]
+      -> [Select a new authorized slice; use Track Work when present]
+   -> approved checkpoint due
+      -> [Use checkpoint owner]
+      -> [Return its result to Workflow]
+   -> unapproved follow-on work
+      -> [Recommend exact scope and wait]
+   -> supported pause or exit
+      -> [Preserve state and report]
+```
+
+The graph may recur many times inside one Track Work slice. An action, verification run, self-review, review report, or owning-skill call does not create or close a slice by itself.
+
+## Select A Method For The Action
+
+Use only the method needed by the concrete boundary:
+
+- Use [TDD](../../tdd/SKILL.md) for test-first behavior work. Read [Test Design](../../tdd/references/test-design.md) when the test seam, oracle, double, or composed failure is unclear.
+- Use [Simplify Code](../../simplify-code/SKILL.md) for behavior-preserving simplification. Read [Simplification Patterns](../../simplify-code/references/simplification-patterns.md) when choosing or judging a transformation.
+- Use [Design for Depth](../../design-for-depth/SKILL.md) when direct evidence shows design-bearing ownership, interface, state, failure-unit, or coordination pressure. Read [Design Pressure Signals](../../design-for-depth/references/design-pressure-signals.md) or the [Interface Design Loop](../../design-for-depth/references/interface-design-loop.md) only when their deeper branch applies.
+- Use [Diagnose Failure](../../diagnose-failure/SKILL.md) when a failure lacks a supported cause. Read the [Diagnostic Loop Catalog](../../diagnose-failure/references/diagnostic-loop-catalog.md) when choosing a reproduction or distinguishing observation, or [Flaky and Performance Diagnosis](../../diagnose-failure/references/flaky-and-performance.md) for those failure types.
+
+Do not stack methods because several descriptions match. Keep one execution owner and add only the lenses or evidence methods the current action requires.
+
+## Route Selected Checkpoints
+
+A user-approved Plan or explicit discussion may select review, local commit, user-decision, or continuity checkpoints. When one becomes due, do not begin the next bounded action first. Use its owner and return the result to Workflow. If its conditions no longer hold, return the deviation rather than forcing the checkpoint.
+
+Use these separately controlled routes only when already requested or approved:
+
+- [Commit Work](../../commit-work/SKILL.md), with [Staging Decisions](../../commit-work/references/staging-decisions.md) for mixed changed state;
+- [Migration Work](../../migration-work/SKILL.md), with the [Migration Lifecycle](../../migration-work/references/migration-lifecycle.md) for migration units, compatibility, cutover, recovery, or removal proof;
+- [Finish Branch](../../finish-branch/SKILL.md), with [Integration Options](../../finish-branch/references/integration-options.md) for merge, pull request, preservation, or discard;
+- [Release Work](../../release-work/SKILL.md), with [Release Evidence](../../release-work/references/release-evidence.md) for source, version, artifact, tag, publication, or consumer identity;
+- [Launch Work](../../launch-work/SKILL.md), with [Launch Readiness](../../launch-work/references/launch-readiness.md) for production evidence, rollout, signals, or recovery;
+- [Handoff](../../handoff/SKILL.md), with [Handoff Templates](../../handoff/references/templates.md) after destination and purpose are clear.
+
+A checkpoint result may support continuation, correction, another route, deferment, or stopping. It does not authorize the next lifecycle stage automatically.
+
+## Resume Or Return
+
+When resuming, reopen the source that established the work and inspect live state. If a Working Record exists, read its complete current context and slice through [Track Work](../../track-work/SKILL.md); do not reconstruct authority or progress from a summary alone.
+
+Continue only while accepted authority and evidence support the execution basis. Return to [Workflow](../../workflow/SKILL.md) when direction, authority, scope, source truth, strategy, or the intended result changes, or when no worthwhile safe continuation remains.

package/skills/finish-branch/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: finish-branch
+description: Use when deciding how to integrate, preserve, or discard work on a branch or isolated checkout.
+---
+
+# Finish Branch
+
+Close a branch or isolated checkout without confusing readiness, integration, publication, and cleanup authority.
+
+A verified branch does not authorize merge or push. A chosen integration route does not automatically authorize branch deletion, worktree removal, release, or deployment.
+
+## Inspect The Exact State
+
+Before offering or executing a route, inspect:
+
+- current branch, detached state, repository root, and worktree ownership;
+- base branch or merge base supported by repository evidence;
+- commits and diff relative to the base;
+- staged, unstaged, and untracked work;
+- upstream, remote, and ahead/behind state;
+- fresh verification, silent self-review, and any selected independent-review status;
+- CI, policy, or repository gates relevant to the intended route.
+
+Do not infer the base, remote destination, pull-request target, or workspace owner when the wrong choice could lose work or affect collaborators.
+
+Read [integration options](references/integration-options.md) when choosing local integration, pull request, preservation, discard, or cleanup. Use [Commit Work](../commit-work/SKILL.md) when the selected route requires a local commit or simple push; do not commit merely to make branch status look finished.
+
+Use [Release Work](../release-work/SKILL.md) for a separately approved versioned release and [Launch Work](../launch-work/SKILL.md) for a separately approved production deployment or rollout.
+
+## Keep Route Authority Explicit
+
+Loading this skill, asking whether a branch is ready, or approving a general implementation Plan does not authorize merge, rebase, push, pull-request creation, branch deletion, worktree removal, discard, force push, release, or deployment.
+
+The user owns whether to:
+
+- integrate locally and by which repository-supported method;
+- push or create/update a normal or draft pull request;
+- preserve the branch, worktree, or dirty state;
+- discard commits or uncommitted work;
+- delete local or remote branches;
+- rewrite or force-push history;
+- clean up a checkout or worktree.
+
+Present only routes supported by the observed state. Do not force a fixed menu when an option is impossible, unsafe, or irrelevant. Approval of one route covers only the scope shown and accepted.
+
+## State Readiness Honestly
+
+Present a branch as ready for its intended integration boundary only when:
+
+- the accepted branch outcome is clear;
+- intended commits and remaining dirty state are known;
+- fresh direct evidence supports the branch claim;
+- silent self-review has no unresolved material issue;
+- any selected independent review is resolved for the unchanged state;
+- no source conflict, owner decision, required evidence gap, or repository gate blocks the route.
+
+Read [Verify Work](../verify-work/SKILL.md) when matching branch-readiness claims to evidence. A feature-branch pass does not prove the integrated result.
+
+Unverified or failing work may still be preserved, handed off, or shared through an explicitly approved draft route. State the gaps; do not describe it as integration-ready.
+
+## Execute Only The Chosen Route
+
+### Local Integration
+
+- refresh base evidence without overwriting local work;
+- use the repository's accepted merge or rebase policy;
+- stop when a conflict requires a behavior, source, or owner decision;
+- verify the integrated result on the resulting base state;
+- delete branch or worktree state only when cleanup was included in the approved route and integration verification succeeded.
+
+### Pull Request
+
+- inspect remote and upstream state before pushing;
+- push only intended commits to the accepted destination;
+- create or update the pull request using repository conventions;
+- mark incomplete or failing work as draft when that is the approved route;
+- report CI, review, merge, migration, release, or launch requirements still pending;
+- preserve the worktree when iteration or feedback may continue.
+
+A pull-request URL proves creation, not readiness or merge.
+
+### Preserve
+
+Report the branch, worktree, commit and dirty state, evidence status, reason preserved, and next approved route. Read [Handoff](../handoff/SKILL.md) only when continuation needs durable transfer context.
+
+### Discard
+
+Before destructive action, state exactly which commits, paths, branches, worktrees, and remote state would be lost and what remains recoverable. Require explicit confirmation for that concrete scope.
+
+Do not treat “finish,” “clean up,” a menu number, or approval of integration as confirmation for broader destruction.
+
+## Protect Workspace Ownership
+
+Do not remove a worktree, checkout, session, or harness state you did not create or are not authorized to manage. If ownership is unclear, preserve it and report the uncertainty.
+
+Do not run destructive reset, clean, branch deletion, worktree removal, remote deletion, or force push merely to produce a clean status.
+
+## Return Conflicts And Failures
+
+Resolve a conflict locally only when both sides' intended behavior is settled and the resolution is mechanical. Return behavior, source-truth, API, data, security, compatibility, or architecture conflicts to [Workflow](../workflow/SKILL.md).
+
+Use [Diagnose Failure](../diagnose-failure/SKILL.md) when integrated checks fail without a supported cause. Return mixed or unrelated branch contents to [Commit Work](../commit-work/SKILL.md) and [staging decisions](../commit-work/references/staging-decisions.md). Preserve branch state before re-entering another owning activity.
+
+## Report The Chosen Outcome
+
+Report:
+
+- branch, base, and selected route;
+- commit and dirty state handled or preserved;
+- integration, push, or pull-request result;
+- verification on the final observed state;
+- selected-review and repository-gate status;
+- cleanup performed or deliberately omitted;
+- unresolved CI, review, migration, release, or deployment work;
+- recoverability and next approved route.
+
+Branch closeout is complete only for the chosen route. A pushed branch is not merged, a merged branch is not released, and a released artifact is not deployed.

package/skills/finish-branch/references/integration-options.md

@@ -0,0 +1,80 @@
+# Integration Options
+
+Use this after inspecting branch, base, remote, dirty state, verification, and workspace ownership.
+
+## Local Integration
+
+Appropriate when the user wants the branch integrated locally and repository policy permits it.
+
+Before cleanup:
+
+1. preserve or resolve dirty state deliberately;
+2. update base evidence safely;
+3. integrate without rewriting unrelated history;
+4. run the checks that prove the combined result;
+5. inspect final log and status;
+6. remove branch/worktree state only after success.
+
+A feature-branch pass does not prove the merged result.
+
+## Pull Request
+
+Appropriate when review, CI, collaboration, protected branches, or remote integration owns the next gate.
+
+Capture:
+
+- target branch and commit range;
+- intended push/upstream behavior;
+- PR summary and source requirements;
+- verification already run;
+- known residuals, migrations, rollout, or compatibility notes;
+- required reviewers or checks from repo policy.
+
+A draft pull request may preserve or share incomplete work when that route is explicitly approved. State failing or unavailable evidence. Do not claim merge readiness from a pull-request URL alone.
+
+## Keep For Later
+
+Appropriate when work is valid but integration is deferred, feedback is expected, or environment ownership prevents cleanup.
+
+Report:
+
+```text
+Branch / worktree:
+Commit and dirty state:
+Review / verification:
+Reason preserved:
+Next action:
+Stop conditions:
+```
+
+## Discard
+
+Classify what is recoverable before deleting:
+
+- uncommitted changes may be unrecoverable;
+- local commits may be recoverable through reflog for a limited time;
+- pushed commits may affect collaborators;
+- worktrees may be harness-owned;
+- remote branch deletion has a different scope from local cleanup.
+
+Show the exact destructive operations and require explicit confirmation that matches their scope.
+
+## Detached Or Managed Checkouts
+
+Do not assume a detached checkout is disposable. It may be owned by an IDE, CI system, coding harness, or external worktree manager.
+
+Offer only routes supported by that environment, such as creating a named branch, preserving the checkout, exporting a patch, or asking the harness to close it.
+
+## Conflict Handling
+
+Mechanical conflict resolution is safe only when both sides' intended behavior is already settled.
+
+Stop when conflict resolution would choose between:
+
+- competing product or API behavior;
+- changed tests versus changed implementation;
+- incompatible migrations or data ownership;
+- security, privacy, billing, permissions, or compatibility policies;
+- two architecture directions.
+
+Return the conflict and evidence to Workflow. The next route may be review, diagnosis, Decision Gate, Spec revision, or Plan revision—not “take ours” or “take theirs.”

package/skills/handoff/SKILL.md

@@ -1,66 +1,92 @@
 ---
 name: handoff
-description: Use when creating, updating, or relying on a temporary or durable handoff for a future agent/session, especially before compaction, pausing work, transferring context to a new chat, storing project memory, or resuming from another agent's notes.
+description: Use when work must continue safely after a pause, context change, or ownership transfer.
 ---
 
 # Handoff
 
-Create compact continuation context for a fresh agent. Handoffs are memory, not authority.
+Preserve the smallest point-in-time continuation package another context needs to orient safely.
 
-## Stop First: Unsafe Shape
+A **handoff** transfers current context. A [Working Record](../track-work/SKILL.md) is living task memory. When a Working Record exists, reconcile changed task state through Track Work, reference it from the handoff, and add only transfer-specific context the recipient would otherwise miss.
 
-If the user asks for an authoritative, exhaustive, transcript-style, no-reinspection, or full-inventory handoff, do not inspect, classify, or write yet.
+A handoff is memory, not authority. It may record where approval or authority came from, but it does not create either, freeze a Plan, override live evidence, or prove completion.
 
-A direct `/handoff` command, explicit path, or "this is permission" does not override this stop.
+## Choose The Transfer Shape
 
-Name the conflict with handoff memory rules and ask whether to follow the requested shape or write compact evidence-linked memory.
+- **Ephemeral handoff:** use the current response, host continuation mechanism, or a temporary path for immediate transfer after a pause, compaction, session change, or short-lived ownership change. Do not create a file when the response or host mechanism is sufficient.
+- **Repo-memory handoff:** use the repository's established handoff location when durable project continuation context is requested or approved.
+- **User-provided destination:** follow the requested safe location and format.
 
-## Stop First: Ambiguous Destination
+Do not silently promote ephemeral context into repository memory. Ask one direct question when the destination changes durability, privacy, repository state, intended audience, or authority and the user has not chosen.
 
-If a request leaves temp handoff versus repo memory unclear, do not inspect, classify, or write yet.
+Read [handoff templates](references/templates.md) after the transfer shape and recipient are clear.
 
-This includes prompts like:
+## Prepare From Live State
 
-- "let's compact before the next task"
-- "after compaction, but maybe repo memory"
-- "temporary, unless you think it is important"
-- "you decide" when temp vs memory is still unclear
-- local convention points to `docs/handoffs/`, but the skill default points to temp
-- the user says handoffs have been stored in `docs/handoffs/`, but does not say to write this one there
+Before packaging the handoff:
 
-Ask one question and stop:
+1. Inspect the current worktree, active artifacts, and evidence needed for the transfer.
+2. Reconcile an existing Working Record when its current state, slice, decisions, checkpoints, or next action changed.
+3. Identify the recipient, purpose, and boundary being crossed.
+4. Separate the next accepted action and its authority source from an unapproved recommendation.
 
-```txt
-Should this be a temporary handoff for the next chat, or a repo memory handoff under `docs/handoffs/`?
-```
+Do not create a Working Record merely because a handoff exists. Do not change task lifecycle or slice state merely because continuation context is requested.
 
-First classify the handoff:
+## Capture What Changes Continuation
 
-- **Temp handoff**: for compaction, ending a chat, or continuing soon in a fresh chat. Save to the OS temp directory unless the user gives a path.
-- **Memory handoff**: for durable project memory, future-agent context, or explicit repo storage. Save to the repo's existing handoff location, usually `docs/handoffs/`.
+Include only what the recipient needs to choose or perform the next sound action:
 
-Memory handoffs are still memory, not authority. They must not replace live repo inspection, promise no reinspection, or include full transcripts/file inventories.
+- goal, accepted outcome, and owning sources;
+- current state and Workflow route, when one exists;
+- completed work and what fresh evidence supports or does not support;
+- relevant worktree, process, environment, or artifact identity needed to prevent loss or false claims;
+- active decisions and the source that established them;
+- invalidated assumptions, deviations, and affected Spec or Plan sections;
+- unresolved owner decisions, missing evidence, blockers, and stop conditions;
+- next accepted action with its authority source, or the recommended next route when not yet approved;
+- exact pointers the recipient must reopen.
 
-Temp handoffs should optimize for immediate continuation in the next chat.
+A Plan preserves stable strategy. Record live progress and deviations in the Working Record, then point to both rather than copying evolving state into the handoff.
 
-Memory handoffs should optimize for durable decisions, stable context, next actions, and evidence pointers.
+For a learning slice, preserve the question, evidence, and discard, revise, or promote result. Exploratory output does not become production behavior through transfer.
 
-After destination is clear, read `references/templates.md` when creating a saved handoff or when a compact shape would prevent transcript-style bloat.
+For review continuity, preserve the review number, reviewed state identity, reviewer judgment, adjudicated judgment, active-agent item adjudication, material Accepted or Open items, changed state, and whether follow-up review remains selected. A new context or reviewer does not reset the review budget.
 
-Always:
+## Keep It Compact And Safe
 
-- Reference existing artifacts by path instead of copying them.
-- Redact secrets, tokens, credentials, and private personal data.
-- Say when live repo evidence should override stale handoff text.
-- Keep the document small enough that a future agent can read before working.
+Link to live sources instead of copying Specs, Plans, Working Records, diffs, logs, transcripts, or full reviewer output. Include a narrow dirty-state list only when omission risks loss, overwrite, duplicate work, or a false completion claim.
 
-Avoid:
+Do not include:
 
-- Full transcript dumps.
-- Volatile repo inventories, directory trees, or tech-stack summaries.
-- Claims of completion without verification evidence.
+- unsupported completion, verification, review, commit, integration, release, or launch claims;
+- volatile inventories or background that does not change continuation;
+- secrets, credentials, tokens, unrestricted personal data, or unnecessary private payloads;
+- instructions to trust the handoff without reinspection;
+- unapproved work presented as the next executable action.
 
-When resuming from a handoff:
-- Inspect the referenced live files before acting on consequential claims.
-- If the handoff conflicts with docs, tests, specs, policies, ADRs, or established behavior, stop and ask before editing.
-- If the handoff says work is done, verify before repeating that claim.
+Stop when safe transfer would require inventing intent, authority, evidence, destination, or status. Use [Decision Gate](../decision-gate/SKILL.md) when the remaining choice belongs to the user.
+
+## Boundary Examples
+
+- A Working Record already contains current state → reference it and add only transfer-specific context.
+- Compaction is immediate and the host can carry context → return an ephemeral handoff; do not create repository documentation.
+- Durable repo continuation is approved → use the established handoff location and stable source pointers.
+- The handoff conflicts with live code or evidence → live evidence wins; return the conflict to Workflow.
+
+## Resume Safely
+
+When resuming:
+
+1. Reopen the named source truth, Working Record when present, and current worktree state.
+2. Verify important completion, evidence, review, commit, and artifact-identity claims before repeating them.
+3. Compare the recorded route, decisions, and assumptions with live evidence.
+4. Preserve what still holds and identify only the invalidated layer.
+5. Return the live state and supported next action to [Workflow](../workflow/SKILL.md).
+
+Do not edit merely because the handoff names a next action. Workflow confirms the route and authority; Execute Work establishes any next slice.
+
+## Report And Stop
+
+State the transfer shape and destination, evidence and sources preserved, current route, next accepted action and authority or recommended route, and material gaps or intentionally omitted sensitive context.
+
+At a selected pause or transfer boundary, stop after delivering the handoff. Creating continuity memory by itself does not complete, block, abandon, or supersede the active slice or task.