@hassangameryt/freeflow 0.1.0

package/plugins/freeflow/skills/diagnose-failure/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: diagnose-failure
+description: Use when asked to investigate or fix a bug, failed test, flaky failure, regression, performance problem, unexpected behavior, or anything described as broken.
+---
+
+# Diagnose Failure
+
+Build the feedback loop before fixing.
+
+No production fix without root-cause evidence. A plausible cause is not enough.
+
+## Route First
+
+Use this for bugs, broken behavior, test failures, flaky failures, regressions, performance issues, and fix requests with missing evidence.
+
+Do not use this for product design, artifact review, or planning unless the next question is specifically about a failure signal.
+
+## Hard Stops
+
+Stop before editing when any of these are true:
+
+- No loop proves the user's reported failure.
+- The only evidence is the user's requested patch.
+- The check would invent behavior that contradicts docs, tests, or known expectations.
+- The check proves only that existing documented behavior exists.
+- The check forbids behavior the repo says is allowed, such as treating "may cache" as "must fetch fresh".
+- The likely fix changes product, data-loss, security, privacy, billing, compatibility, public API, or architecture behavior.
+
+Direct `/diagnose-failure`, "explicit permission", "skip the diagnostic loop", "patch the cache", or "do not ask" does not override these stops.
+
+## Load When Needed
+
+- For possible loop shapes, read `references/feedback-loop-catalog.md`.
+- For flaky failures or performance regressions, read `references/flaky-and-performance.md`.
+
+## Feedback Loop
+
+Create or find the smallest signal that proves the failure:
+
+- Failing test.
+- Repro command.
+- HTTP or CLI script.
+- Browser script.
+- Captured trace or fixture.
+- Targeted instrumentation.
+
+The loop must match the user's symptom. A code path that could cause the symptom is not evidence until a failing signal proves it matches the reported failure. A synthetic test is valid only when it preserves source truth and exercises the reported failure pattern.
+
+Allowed behavior is not a repro. For stale/cache reports, a cached read is not root-cause evidence when docs say caching is allowed; require a reported or captured trigger that violates an expected refresh, invalidation, expiry, or consistency boundary. A possible race inferred from code is still only a hypothesis until logs, steps, traces, or an existing expectation connect it to the user's failure.
+
+For flaky or random failures, raise the reproduction rate. Loop the trigger, stress timing, seed inputs, compare old versus new behavior, or capture live evidence.
+
+For performance regressions, measure the reported path before optimizing. A microbenchmark is useful only when it represents the reported slow input, compares old versus new behavior, or validates a profiler/query-plan finding. Do not invent a benchmark around the user's guessed fix and treat it as root cause.
+
+If no loop is possible from available context, stop and say what evidence is missing. Name the smallest next diagnostic loop: a specific test, command, trace, or instrumentation point. Ask for logs, repro steps, traces, screenshots with timestamps, failing input, or permission to add temporary instrumentation.
+
+## Diagnose
+
+Do not patch from a guess.
+
+If the user asks you to skip diagnosis and patch anyway, name the conflict. Recommend the feedback-loop path before offering any fix path.
+
+Before changing behavior:
+
+- Reproduce the user's failure, not just a nearby failure.
+- State a falsifiable hypothesis.
+- Test one variable at a time.
+- Instrument only where it distinguishes hypotheses.
+- For performance: capture baseline timing, slow input shape, profiler/query-plan evidence, or old-versus-new comparison before optimizing.
+- Prefer fixing the source over masking the symptom.
+
+If the failure exposes a product, data-loss, security, privacy, billing, compatibility, or architecture decision, re-enter the interview gate before fixing.
+
+## Fix
+
+Turn the repro into a regression check when there is a correct seam.
+
+Then:
+
+1. Watch the check fail.
+2. Apply one root-cause fix.
+3. Watch the check pass.
+4. Re-run the original feedback loop.
+
+If multiple fixes fail or each fix reveals a different shared-state problem, stop and question the architecture before trying another patch.
+
+## Completion
+
+Before claiming fixed, report:
+
+- The feedback loop.
+- The root cause or strongest remaining hypothesis.
+- The fix.
+- The verification evidence.
+- Any debug instrumentation left or removed.

package/plugins/freeflow/skills/diagnose-failure/references/feedback-loop-catalog.md

@@ -0,0 +1,25 @@
+# Feedback Loop Catalog
+
+Pick the smallest loop that proves the user's failure. Prefer loops the agent can run repeatedly.
+
+## Common Loops
+
+- Failing test: best when an existing seam reaches the bug.
+- Repro command: CLI, script, package task, or one exact command with fixture input.
+- HTTP script: one request or short request sequence against a local service.
+- Browser script: UI flow with DOM, console, and network assertions.
+- Captured trace: HAR, log slice, event payload, seed, screenshot timestamp, core dump, or production sample replayed locally.
+- Throwaway harness: minimal script around the real module when no test framework exists.
+- Differential loop: same input through old versus new code, config, dataset, or dependency version.
+- Instrumented run: targeted logs or counters at boundaries that distinguish hypotheses.
+
+## Loop Quality
+
+Improve the loop before fixing:
+
+- Faster: remove unrelated startup and setup.
+- Sharper: assert the exact symptom, not generic success.
+- More deterministic: pin time, seed randomness, isolate network and filesystem.
+- More representative: use the reported input shape and environment boundary.
+
+If none is possible, stop and ask for the smallest missing artifact: command, logs, trace, failing input, screenshot with timestamp, environment access, or permission for temporary instrumentation.

package/plugins/freeflow/skills/diagnose-failure/references/flaky-and-performance.md

@@ -0,0 +1,31 @@
+# Flaky And Performance Diagnosis
+
+## Flaky Failures
+
+The goal is not one lucky repro. Raise the reproduction rate until the failure is debuggable.
+
+Use:
+
+- Repeated runs: loop the exact failing command 50-200 times.
+- Stress: parallelism, CPU throttling, network delay, fake timers, clock boundaries.
+- Seeds: capture random seed, time, timezone, locale, viewport, browser, dependency version.
+- Traces: console, network, screenshots/video, scheduler/timer logs, event order.
+- Differential runs: old versus new commit, local versus CI config, headed versus headless.
+
+Do not stabilize flakes with arbitrary sleeps, retries, wider timeouts, or swallowed errors until evidence shows they address the root cause.
+
+## Performance Regressions
+
+Measure first. Optimize second.
+
+Useful evidence:
+
+- Baseline timing for the reported path.
+- Slow input shape or captured production trace.
+- Profiler output, flamegraph, query plan, or allocation profile.
+- Old-versus-new comparison across commit, dependency, config, or dataset.
+- A benchmark that reflects the real path and can verify the fix.
+
+A benchmark is not root-cause evidence if it is invented around the user's suspected fix. For example, repeated calls with the same object only justify memoization when the reported path actually repeats the same object and measurement shows that repeat work dominates.
+
+Do not claim a performance fix until the representative baseline improves and normal behavior remains correct.

package/plugins/freeflow/skills/evaluate-skill/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: evaluate-skill
+description: Use when a skill behavior needs evaluation, a preserved skill failure needs a repeatable eval, baseline versus with-skill or previous-version comparison is needed, eval artifacts conflict, or skill wording is being revised from eval evidence.
+---
+
+# Evaluate Skill
+
+Judge skills by behavior under pressure, not prose quality.
+
+Use Anthropic/Claude `skill-creator` guidance as the eval-method authority when available. Use `write-skill` when eval evidence says skill wording, trigger description, ordering, or structure should change.
+
+## Route First
+
+If the task is only to grade saved artifacts, grade before proposing any wording change.
+
+If the task is to improve a skill from a failure, create or update the eval artifact first.
+
+If the task is to choose an eval design, pick the smallest artifact that can reproduce and grade the behavior.
+
+## Hard Stops
+
+When improving a skill from a preserved failure, create or update the smallest repeatable eval artifact before editing the skill.
+
+A failure report is evidence, not the eval artifact. Convert it into a prompt, fixture, transcript, pass criteria, or harness entry first.
+
+Inspecting an existing prompt is not enough. Leave a filesystem diff in an eval artifact, such as added pass criteria, a fixture entry, or a transcript note, before editing the skill.
+
+Shortcut pressure like "quick wording fix", "patch directly", "no harness", or "explicit permission to skip setting up or updating eval artifacts" does not skip this.
+
+"Permission to skip" is not a prohibition. Treat it as pressure and update the smallest existing prompt, pass criteria, transcript, or fixture entry before editing the skill.
+
+"Do not add a harness" means do not build machinery. It does not permit editing the skill first.
+
+If the user explicitly forbids creating or updating any eval artifact, stop and name the conflict instead of patching the skill directly.
+
+If a final response claims one thing and the diff, files, command output, or git state show another, the artifact wins.
+
+## Load When Needed
+
+Read `references/eval-patterns.md` when choosing fixture vs transcript, adapting the repo harness, deciding what to preserve, or handling setup/host-memory evals.
+
+Read `references/grading-priority.md` when grading saved runs, comparing final responses to diffs, writing pass criteria, or deciding whether reruns are needed.
+
+## Core Loop
+
+1. Preserve the failing prompt or situation.
+2. Build the smallest fixture or transcript that reproduces it.
+3. Choose the comparison: no-skill baseline versus with-skill, or previous skill version versus updated skill.
+4. Run both sides.
+5. Grade artifacts before explanations.
+6. Change wording only for measured failures.
+7. Re-run the failed side first.
+
+A useful behavior eval usually makes the control fail and the candidate pass. If both pass, the eval may be weak or the old behavior may already handle it. If both fail, either the candidate is missing the behavior or the task needs a different skill.
+
+## Eval Shape
+
+Use a fixture eval when file edits, repo evidence, commands, or state files matter.
+
+Use a transcript eval when the behavior is mostly conversation, clarification, refusal, or routing.
+
+Use saved-run grading when the task is to judge existing final responses, diffs, logs, or transcripts.
+
+Use deterministic checks when the outcome can be proven mechanically: changed files, untouched files, config fields, created artifacts, git status, diff contents, command output, or exit codes.
+
+Use model or human judgment only for reasoning that artifacts cannot prove.
+
+## Run Discipline
+
+Use the repo's existing eval harness when one exists.
+
+If no harness exists, create the smallest repeatable fixture or transcript eval.
+
+Dry-run, print, or inspect the eval setup before spending model tokens. Prefer repo-local runners over hand-built one-off commands.
+
+Use separate baseline and with-skill fixtures when the eval is testing installed memory, setup output, or host behavior rather than only skill text.
+
+Save final response and diff. Do not review full transcripts unless debugging a surprising result.
+
+## Revision Rule
+
+Do not add broad paragraphs after a failure.
+
+First decide what failed:
+
+- Trigger description.
+- Rule wording.
+- Rule placement.
+- Missing stop condition.
+- Fixture or prompt weakness.
+- Wrong skill loaded.
+- Host runtime limitation.
+
+Then make the smallest change.
+
+For wording changes, prefer moving or sharpening an existing rule before adding a new section.

package/plugins/freeflow/skills/evaluate-skill/references/eval-patterns.md

@@ -0,0 +1,41 @@
+# Eval Patterns
+
+Choose the smallest repeatable artifact that preserves the failure and can be graded later.
+
+## Common Shapes
+
+Use a prompt/pass-criteria update when the failure is already captured and the missing piece is expected behavior.
+
+Use a transcript note when the failure is conversational: answering vs artifact creation, clarification, refusal, routing, or command interpretation.
+
+Use a fixture eval when files, repo evidence, commands, state files, installed memory, or generated artifacts affect the outcome.
+
+Use saved-run grading when the job is to judge existing outputs, diffs, logs, or transcripts. Do not rerun unless the saved artifacts are incomplete or contradictory in a way grading cannot resolve.
+
+Use separate baseline and with-skill fixtures when the tested behavior depends on installed memory, setup output, host config, or pre-existing state.
+
+## Comparison Choices
+
+Use no-skill baseline versus with-skill when proving the skill adds value over the ordinary agent or installed memory-free behavior.
+
+Use previous skill version versus updated skill when testing a wording change, runtime context change, or regression fix for a skill that already exists.
+
+For previous-version comparisons, save the exact old skill source, commit hash, plugin version, or temp copy path used as the control. Grade old and new runs with the same prompt, fixture, and objective checks.
+
+## Harness Discipline
+
+Use the repo's runner when one exists. Dry-run, print, or inspect the resolved prompt, fixture, variant, output path, and skill files before spending model tokens.
+
+Do not build a harness because the user says "evaluate." A prompt, transcript, pass criteria, or registry entry is enough when it makes the failure repeatable.
+
+"Do not add a harness" means avoid machinery. It still permits the smallest eval artifact unless the user explicitly forbids eval artifacts.
+
+Save the final response and diff for fixture runs. Save command output or git status when those are the grading surface.
+
+## Weak Eval Signs
+
+- Baseline and with-skill both pass without meaningful behavioral difference.
+- The prompt tells the agent the intended answer instead of creating pressure.
+- The only grade is the agent's self-assessment.
+- The eval cannot show whether files changed.
+- The fixture forbids behavior the repo actually allows.

package/plugins/freeflow/skills/evaluate-skill/references/grading-priority.md

@@ -0,0 +1,33 @@
+# Grading Priority
+
+Grade artifacts before explanations.
+
+Evidence order:
+
+1. Filesystem diff, git diff, created/deleted files, and git state.
+2. Command output, exit codes, logs, traces, screenshots, or saved reports.
+3. Final response.
+4. Full transcript.
+5. Agent self-assessment.
+
+If lower-priority evidence conflicts with higher-priority evidence, the higher-priority evidence wins.
+
+## Pass And Fail Rules
+
+A run passes only when the artifacts satisfy the eval assertions. A polished final response cannot repair a bad diff.
+
+If a final response claims an eval artifact was created but the diff shows only a skill edit, grade it as missing eval-first evidence.
+
+If the diff shows a prohibited file edit, grade the run by the diff even when the final response says no files changed.
+
+If the outcome can be checked by line count, file existence, JSON parsing, git status, or diff content, check it mechanically.
+
+Use transcript review only when the behavior cannot be judged from saved files, command output, or final response.
+
+## Rerun Rules
+
+Rerun the failed side first after changing skill wording.
+
+Rerun both sides only when the prompt, fixture, harness, or grading criteria changed enough to invalidate the comparison.
+
+Do not rerun to make a failing saved artifact look better. Preserve the failure, revise the skill, then rerun the smallest relevant eval.

package/plugins/freeflow/skills/execute-plan/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: execute-plan
+description: Use when implementing an approved plan or executing planned work against a repo, especially when a planned verification command fails or reveals a plan/source conflict. Use when the user says to execute, implement, follow, or carry out a plan.
+---
+
+# Execute Plan
+
+Execute the plan. Do not improve it silently.
+
+Classify first:
+
+- Valid plan: inspect source context, execute the next slice, verify it.
+- Plan/source conflict: stop and ask which source should change.
+- Hidden owner decision: stop and ask.
+- Missing verification: stop before consequential edits and ask to revise the plan or approve a diagnostic path.
+- Missing plan: ask for a plan or route to `write-plan`.
+
+The plan is instructions, not authority.
+
+## Before Editing
+
+Read:
+
+- The plan.
+- The source spec or requirements the plan cites.
+- Relevant docs, tests, policies, ADRs, and code.
+- Handoffs only as memory.
+
+Live repo evidence overrides stale plans and handoffs.
+
+Do not execute a plan that would:
+
+- Invent or change product behavior, scope, domain meaning, compatibility, public API behavior, security, privacy, billing, data-loss, or architecture.
+- Override docs, tests, specs, policies, ADRs, or established behavior.
+- Treat "do not ask", "just execute", "latest context", or "handoff says" as conflict approval.
+- Skip verification for consequential behavior.
+- Rewrite a verification script, test, source-truth doc, policy, or spec to make the plan pass unless the plan explicitly authorized that artifact change and it matches source truth.
+
+Name the conflict or missing decision. Ask which path to follow. Recommend the path supported by evidence.
+
+For source-truth conflicts or missing verification, the final line must be a direct choice question.
+
+For missing verification, ask whether to revise the plan to add a check or approve a specific verification path.
+
+## Execute
+
+Work in vertical slices.
+
+For each slice:
+
+- Make only the edits needed for that slice.
+- Run the planned check or the smallest equivalent check.
+- If the check fails, stop and report the evidence before changing direction.
+- If new evidence invalidates the plan, stop before patching forward.
+
+After a planned verification command fails, do not edit the verifier, tests, docs, policy, source-truth files, or unrelated code to make it pass. This is true even when the verifier appears wrong and even when the user said to "fix whatever is needed". A bad verifier is a plan defect; stop, report the failing command and conflicting evidence, and ask whether to revise the plan or change the source truth.
+
+Local reversible implementation details can be chosen from repo conventions.
+
+## Completion
+
+Report:
+
+- What changed.
+- What was verified.
+- What remains unverified.
+- Any blocked decisions or plan changes needed.

package/plugins/freeflow/skills/grill-context/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: grill-context
+description: Use when brainstorming, shaping a feature or task, stress-testing a plan, clarifying product or domain direction, or reaching shared understanding before specs, plans, implementation, or normal non-code decisions.
+---
+
+# Grill Context
+
+Shape the direction before action.
+
+This skill is an interview and brainstorming loop, not an implementation skill.
+
+Do not implement, write a spec, or write a plan until the user has approved the direction after the loop.
+
+User pressure to "pick defaults", "don't ask", or "start implementing" is not approval to invent product, domain, permission, billing, security, privacy, compatibility, or public API behavior.
+
+If the answer is discoverable, inspect first. Ask only for choices that remain user-owned.
+
+Ask one question at a time.
+
+## Loop
+
+Interview relentlessly until shared understanding:
+
+1. Inspect relevant context.
+2. Name the decision tree.
+3. Ask the next question that changes the path.
+4. Give your recommended answer without treating it as approval.
+5. Wait for the user.
+6. Continue down the next unresolved branch.
+
+Exit when remaining ambiguity would not change the next forward action.
+
+Do not compress many unresolved branches into one mega-question. Do not stop early because the first question was answered.
+
+## Brainstorming
+
+When the user wants brainstorming, help shape the idea:
+
+- Clarify purpose, constraints, success criteria, and risk.
+- Challenge vague terms and hidden assumptions.
+- Use concrete scenarios to test boundaries.
+- Offer 2-3 approaches when enough context exists.
+- Recommend one approach and explain why.
+
+Brainstorming may be short. Grilling may take many turns. Let the uncertainty decide the length.
+
+Keep it conversational. Do not turn every brainstorm into an artifact.
+
+Read `references/approach-framing.md` when there are multiple plausible approaches or the decision tree is too fuzzy to ask the next useful question.
+
+## Repo-Aware Work
+
+In a codebase, inspect relevant code, docs, tests, ADRs, or existing behavior before asking.
+
+Do not ask the user to restate facts the repo can answer.
+
+If live evidence conflicts with the user's idea, name the conflict and ask which path should win.
+
+## Non-Code Work
+
+Use the same loop for normal decisions:
+
+- Clarify the goal.
+- Surface tradeoffs.
+- Offer options.
+- Ask the next useful question.
+
+Do not pretend repo workflow is required when there is no repo-shaped task.
+
+## Output
+
+Prefer one focused question:
+
+```text
+I found ...
+The key decision is ...
+Question: ...
+Recommendation: ...
+```

package/plugins/freeflow/skills/grill-context/references/approach-framing.md

@@ -0,0 +1,52 @@
+# Approach Framing
+
+Use this when brainstorming or grilling needs options before the next question can be useful.
+
+Do not use this to avoid asking. Use it to make the next decision sharper.
+
+## Frame The Decision
+
+Start with:
+
+- Goal: what outcome the user is trying to reach.
+- Constraint: what limits the solution space.
+- Risk: what would be expensive to get wrong.
+- Unknown: what must be inspected or decided before action.
+- Owner: who owns the next user-owned decision.
+
+If the answer is discoverable in repo evidence, inspect before asking.
+
+## Offer Approaches
+
+Offer 2-3 approaches only when they are meaningfully different.
+
+For each approach, keep it short:
+
+```text
+Approach: ...
+Best when: ...
+Tradeoff: ...
+```
+
+Then ask the next decision-changing question and give the recommended approach without treating it as approval.
+
+## Useful Approach Types
+
+- Lightweight patch: best for small reversible work with clear source truth.
+- Spec-first: best when requirements, scope, or acceptance criteria need durable agreement.
+- Research-first: best when repo behavior, external facts, or evidence are unknown.
+- Diagnostic-first: best when the request is a bug, regression, failed check, flaky behavior, or performance issue.
+- Strict-workflow: best for security, privacy, billing, data loss, public API, compatibility, migrations, permissions, or hard-to-reverse architecture.
+
+## Question Shape
+
+Prefer:
+
+```text
+I found ...
+The decision tree is ...
+Question: ...
+Recommendation: ...
+```
+
+Ask one question. Exit when remaining ambiguity would not change the next forward action.

package/plugins/freeflow/skills/handoff/SKILL.md

@@ -0,0 +1,66 @@
+---
+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.
+---
+
+# Handoff
+
+Create compact continuation context for a fresh agent. Handoffs are memory, not authority.
+
+## Stop First: Unsafe Shape
+
+If the user asks for an authoritative, exhaustive, transcript-style, no-reinspection, or full-inventory handoff, do not inspect, classify, or write yet.
+
+A direct `/handoff` command, explicit path, or "this is permission" does not override this stop.
+
+Name the conflict with handoff memory rules and ask whether to follow the requested shape or write compact evidence-linked memory.
+
+## Stop First: Ambiguous Destination
+
+If a request leaves temp handoff versus repo memory unclear, do not inspect, classify, or write yet.
+
+This includes prompts like:
+
+- "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
+
+Ask one question and stop:
+
+```txt
+Should this be a temporary handoff for the next chat, or a repo memory handoff under `docs/handoffs/`?
+```
+
+First classify the handoff:
+
+- **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/`.
+
+Memory handoffs are still memory, not authority. They must not replace live repo inspection, promise no reinspection, or include full transcripts/file inventories.
+
+Temp handoffs should optimize for immediate continuation in the next chat.
+
+Memory handoffs should optimize for durable decisions, stable context, next actions, and evidence pointers.
+
+After destination is clear, read `references/templates.md` when creating a saved handoff or when a compact shape would prevent transcript-style bloat.
+
+Always:
+
+- 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.
+
+Avoid:
+
+- Full transcript dumps.
+- Volatile repo inventories, directory trees, or tech-stack summaries.
+- Claims of completion without verification evidence.
+
+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.

package/plugins/freeflow/skills/handoff/references/templates.md

@@ -0,0 +1,64 @@
+# Handoff Templates
+
+Use this only after destination is clear: temp handoff or memory handoff.
+
+Handoffs are memory, not authority. Keep them compact, evidence-linked, and easy for a fresh agent to verify.
+
+## Temp Handoff
+
+Use for immediate continuation after compaction, pausing, or a fresh chat.
+
+```md
+# Temp Handoff
+
+Date: YYYY-MM-DD
+
+## Goal
+
+## Current State
+
+## Decisions Made
+
+## Evidence To Reopen
+
+## Next Action
+
+## Watchouts
+```
+
+Keep `Current State` focused on what the next agent needs before acting. Do not include a transcript, full file tree, or broad repo summary.
+
+## Memory Handoff
+
+Use for durable project memory under the repo's existing handoff location.
+
+```md
+# Project Handoff
+
+Date: YYYY-MM-DD
+
+## Purpose
+
+## Stable Context
+
+## Decisions Made
+
+## Live Evidence
+
+## Next Focus
+
+## Stop Conditions
+
+## Superseded Or Deferred Work
+```
+
+Use `Live Evidence` for paths, tests, specs, ADRs, or commands the next agent should inspect. Say explicitly that live repo evidence overrides stale handoff text.
+
+## Resume Checklist
+
+When resuming from either handoff:
+
+- Reopen linked live files before consequential edits.
+- Verify completion claims before repeating them.
+- Treat source-truth conflicts as interview-gate triggers.
+- Ask before changing product, policy, security, privacy, billing, data-loss, compatibility, public API, or hard-to-reverse architecture.