@hassangameryt/freeflow 0.2.0 → 0.4.0

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

@@ -1,95 +0,0 @@
----
-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

@@ -1,25 +0,0 @@
-# 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

@@ -1,31 +0,0 @@
-# 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

@@ -1,96 +0,0 @@
----
-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

@@ -1,41 +0,0 @@
-# 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

@@ -1,33 +0,0 @@
-# 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

@@ -1,132 +0,0 @@
----
-name: execute-plan
-description: Use when implementing an approved plan, executing planned slices, resuming planned work, handling planned verification failures, adjudicating review findings during execution, or encountering scope/source conflicts while carrying out a plan.
----
-
-# Execute Plan
-
-Execute the plan. Do not improve it silently.
-
-The plan is instructions, not authority. Live repo evidence and source truth win.
-
-Move one verified slice at a time. Preserve rollback, reviewability, and user control.
-
-Read `references/execution-map.md` when the plan has multiple slices, TDD/benchmark work, review checkpoints, per-slice commits, context-window pressure, or any failed check/review/source-scope conflict.
-
-Keep research language alive. Read `../research/LANGUAGE.md` when a slice changes modules, interfaces, seams, adapters, architecture, or when review findings become a stream of edge-case patches. Ask whether the slice is deepening the module or spreading complexity across callers, tests, docs, or review comments.
-
-## 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`.
-- Scope expansion: stop before absorbing it; route back to research, spec, or plan.
-- Review failure during execution: classify findings and report the route before editing from them.
-
-## 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.
-
-Before each non-trivial slice, name the slice contract:
-
-```text
-Slice:
-Source truth:
-Module/interface changed:
-Behavior/test/benchmark:
-Verification:
-Review checkpoint:
-Commit or handoff checkpoint:
-Stop conditions:
-```
-
-Do not start a slice if the remaining context is not enough to orient, edit, verify, and checkpoint it. Stop with a handoff route instead.
-
-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.
-
-## Slice Execution
-
-Work in vertical slices.
-
-For each slice:
-
-- Make only the edits needed for that slice.
-- Keep the slice boundary intact; do not blend future slices into the current one for convenience.
-- 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.
-
-When TDD is requested by the user, plan, or repo practice, use TDD inside the slice:
-
-```text
-one behavior test or benchmark
--> minimal implementation
--> refactor while green
--> verify the slice
-```
-
-Do not write all tests first and all implementation later. Do not anticipate future slices.
-
-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.
-
-If per-slice commits are requested, do not continue to the next slice with a verified slice still uncommitted. Route to `commit-work` after review/verification evidence exists.
-
-## Review Checkpoints
-
-Use review where the plan, risk, or slice boundary calls for it. Do not review every slice by habit.
-
-A non-passing review is a phase exit, not an autonomous patch loop.
-
-When a review returns findings during execution:
-
-1. Inspect the relevant code, tests, docs, plan, and source truth.
-2. Classify each material finding: accepted, rejected, question, or needs evidence.
-3. Report the route before editing from that review batch.
-
-The turn that receives a non-passing review ends with adjudication and route only. Do not edit from that review batch in the same turn, even when the user or reviewer says to apply all findings and continue reviewing.
-
-Do not immediately apply findings and request another review in the same loop. Do not treat non-blocking findings or reviewer questions as automatic failure.
-
-If all accepted findings are small, in-scope, and supported by source truth, recommend a bounded fix pass as the next route. Do not perform that fix pass until the user or parent explicitly chooses it after seeing the adjudication. If findings change scope, behavior, source truth, public API, security, privacy, billing, data loss, compatibility, or architecture, route backward before editing.
-
-Three review passes is the hard cap for the same slice/work scope. At pass 3, stop, classify, and diagnose. Do not request a fourth broad review. Use a `diagnose-failure`-style loop to decide whether the issue is shallow research, weak spec, wrong plan slice, ambiguous policy, source-truth conflict, shallow module/interface, implementation bug, or stale reviewer context.
-
-## Backward Edge
-
-If implementation reveals that the plan is wrong, incomplete, or too narrow, re-enter research/spec/plan before continuing.
-
-Do not absorb material scope expansion into execution. New behavior, API shape, security/privacy/billing/data-loss decisions, compatibility changes, or irreversible architecture usually need a revised spec or plan.
-
-## Completion
-
-Report:
-
-- What changed.
-- What was verified.
-- Review status and any adjudicated findings.
-- Commit or handoff status when relevant.
-- What remains unverified.
-- Any blocked decisions or plan changes needed.

package/plugins/freeflow/skills/execute-plan/references/execution-map.md

@@ -1,122 +0,0 @@
-# Execute Plan Map
-
-Use this when carrying out a multi-slice plan, resuming from handoff, combining TDD with execution, deciding whether to review/commit, or handling failed checks/reviews/scope changes.
-
-The map is a control surface, not ceremony. Small reversible slices can use the compact map only.
-
-## Compact Map
-
-```text
-Orient
--> Slice contract
--> Red / Green / Refactor when TDD applies
--> Verify
--> Review checkpoint when needed
--> Commit or handoff checkpoint when needed
--> Next slice
-
-Any failed check, non-pass review, source conflict, or scope expansion
--> Classify evidence
--> Report route
--> Fix | Diagnose | Research | Spec | Plan | Stop
-```
-
-## Contract Map
-
-Before a non-trivial slice, name:
-
-```text
-Slice: what part of the plan is active
-Source truth: spec/docs/tests/policies/code that own behavior
-Module/interface changed: outside contract affected by this slice
-Behavior/test/benchmark: observable behavior to prove
-Verification: command or check that proves this slice
-Review checkpoint: none | after this slice | after stack | final
-Commit or handoff checkpoint: when rollback/resume needs a snapshot
-Stop conditions: decisions/conflicts/failures that end the slice
-```
-
-A slice contract prevents hidden broadening. If the contract changes materially, stop and route backward.
-
-## Reference Map
-
-```mermaid
-flowchart TD
-  Start([Plan or handoff]) --> Orient[Orient<br/>read plan, source truth, live code]
-  Orient --> Contract[Slice contract<br/>boundary + interface + checks]
-  Contract --> Decision{Can execute safely?}
-
-  Decision -->|yes| Build[Build slice<br/>TDD vertical loop if applicable]
-  Decision -->|missing plan/check/decision| Back[Backward route<br/>research / spec / plan / owner]
-
-  Build --> Verify[Verify planned check]
-  Verify -->|pass| ReviewGate{Review needed now?}
-  Verify -->|fail| Fail[Classify failure evidence]
-
-  ReviewGate -->|no| Checkpoint[Commit/handoff checkpoint if needed]
-  ReviewGate -->|yes| Review[Review checkpoint]
-  Review -->|pass| Checkpoint
-  Review -->|non-pass| ReviewFail[Classify findings<br/>accepted / rejected / question / needs evidence]
-
-  Checkpoint --> Next{Next slice?}
-  Next -->|yes| Orient
-  Next -->|no| Done([Complete / final verify / handoff])
-
-  Fail --> Route{Route}
-  ReviewFail --> Route
-  Route -->|next bounded fix| Build
-  Route -->|unclear or repeated| Diagnose[Diagnose]
-  Route -->|source/scope decision| Back
-  Diagnose --> Back
-```
-
-## Entry Points
-
-Use this map when the current task is:
-
-- start or continue an approved plan;
-- execute the next planned slice;
-- resume from a handoff;
-- run a TDD or benchmark-backed implementation slice;
-- handle a planned verification failure;
-- handle review findings during execution;
-- decide whether to commit after a slice;
-- context is getting low before the next slice;
-- implementation reveals scope or source truth changed.
-
-## Exits
-
-- **Forward** — slice verified; next slice boundary is clear.
-- **Bounded fix** — accepted finding/check failure is small, in-scope, and source-truth-supported.
-- **Commit checkpoint** — verified slice should be committed before continuing.
-- **Handoff checkpoint** — context is too low or continuation state must survive.
-- **Backward** — scope/source truth/review evidence invalidates the plan.
-- **Diagnose** — repeated failure or edge-case patching suggests a deeper problem.
-- **Stop** — blocked on owner decision or plan/spec/source change.
-
-## Review Failure Routing
-
-A non-pass review is not an edit script.
-
-Classify before action:
-
-- **Accepted** — valid, source-truth-supported, and in scope.
-- **Rejected** — stale, unsupported, already resolved, equivalent, or not important.
-- **Question** — needs owner/product/domain/security/API/etc. decision.
-- **Needs evidence** — inspect before deciding.
-
-Route:
-
-- Accepted + bounded + in scope -> recommend one fix pass next; do not perform it in the same turn that received the non-pass review.
-- Non-blocking -> defer or bundle only when safe.
-- Question -> ask; do not implement the answer silently.
-- Needs evidence -> inspect or diagnose before editing.
-- Third review pass -> diagnose; no fourth broad review.
-
-Repeated edge-case findings are a design signal. Ask whether the module/interface is too shallow, the plan slice is wrong, the spec is under-specified, or reviewer context is stale.
-
-## Context And Snapshot Discipline
-
-Do not start a slice if you cannot finish the edit, verification, and checkpoint in the current context window.
-
-When per-slice commits are requested, a verified slice should route to `commit-work` before the next slice. When a commit is not appropriate, make a handoff if future execution depends on the slice state.

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

@@ -1,66 +0,0 @@
----
-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.