@hassangameryt/freeflow 0.3.0 → 0.5.0

package/skills/handoff/references/templates.md

@@ -1,64 +1,141 @@
 # Handoff Templates
 
-Use this only after destination is clear: temp handoff or memory handoff.
+Read this after the transfer shape, recipient, and purpose are clear. Omit every field that does not change safe continuation.
 
-Handoffs are memory, not authority. Keep them compact, evidence-linked, and easy for a fresh agent to verify.
+Handoffs are memory, not authority. Live sources and repository state override stale handoff text.
 
-## Temp Handoff
+## Ephemeral Handoff
 
-Use for immediate continuation after compaction, pausing, or a fresh chat.
+Use in the current response, a host continuation mechanism, or a temporary file for immediate continuation.
 
 ```md
-# Temp Handoff
+# Continuation Handoff
 
-Date: YYYY-MM-DD
+Generated: <optional reliable date or time>
+Recipient / purpose:
 
-## Goal
+## Goal And Owning Sources
 
 ## Current State
+- Workflow route:
+- Working Record, Spec, or Plan pointers:
+- Relevant source or artifact identity:
 
-## Decisions Made
+## Completed Work And Evidence
+- Result:
+- Evidence:
+- Supports:
+- Does not support:
 
-## Evidence To Reopen
+## Decisions And Authority
+- Decision:
+- Established by:
+- Scope:
+
+## Deviations Or Invalidated Assumptions
+
+## Worktree, Process, Or Environment Watchouts
+
+## Review Continuity
+
+## Open Decisions, Evidence, Or Blockers
 
 ## Next Action
+- Accepted action:
+- Authority source:
 
-## Watchouts
+Or, when not approved:
+- Recommended route:
+- Approval or decision needed:
+
+## Stop Conditions
 ```
 
-Keep `Current State` focused on what the next agent needs before acting. Do not include a transcript, full file tree, or broad repo summary.
+Keep dirty-state details narrow. Include only paths, processes, environments, or artifacts whose omission risks loss, overwrite, duplicate work, or a false claim.
 
-## Memory Handoff
+## Repo-Memory Handoff
 
-Use for durable project memory under the repo's existing handoff location.
+Use for durable project continuation in the repository's established location.
 
 ```md
 # Project Handoff
 
-Date: YYYY-MM-DD
+Generated: <optional reliable date or time>
+Recipient / purpose:
+
+## Goal And Accepted Outcome
 
-## Purpose
+## Owning Sources
 
 ## Stable Context
 
-## Decisions Made
+## Current State And Evidence
 
-## Live Evidence
+## Working Record, Spec, And Plan Pointers
 
-## Next Focus
+## Decisions, Authority, And Approval Scope
 
-## Stop Conditions
+## Deviations, Invalidated Assumptions, Or Superseded Direction
+
+## Review Continuity
+
+## Open Decisions, Evidence Gaps, And Stop Conditions
 
-## Superseded Or Deferred Work
+## Next Accepted Action
+- Action:
+- Authority source:
+
+Or:
+
+## Recommended Next Route
+- Route:
+- Approval or decision needed:
 ```
 
-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.
+Do not copy living progress from a Working Record or turn directional Plan content into committed work. Preserve only stable or transfer-critical context that belongs in the handoff.
 
-## Resume Checklist
+## Learning-Slice Addendum
 
-When resuming from either handoff:
+Include when an experiment, prototype, benchmark, or investigation changed the route:
+
+```md
+Question:
+Competing hypotheses or designs:
+Evidence captured:
+Result: discard | revise | promote | inconclusive
+Exploratory artifacts retained:
+Affected Working Record, Spec, Plan, or later work:
+Next accepted action and authority, or recommended route:
+```
+
+Promotion records a decision; it does not itself authorize production implementation.
+
+## Review-Continuity Addendum
+
+Include only when review state must survive the transfer:
+
+```md
+Review number: 1 | 2 | 3
+Reviewed state identity:
+Reviewer judgment: Pass | Non-blocking | Inconclusive | Blocking
+Adjudicated judgment: Pass | Non-blocking | Inconclusive | Blocking
+Material review items and evidence pointers:
+Active-agent item adjudication:
+- <item>: Accepted | Rejected | Open — <reason>
+Accepted Blocking or Non-blocking Issues:
+Material Open items:
+Changed areas after review:
+Follow-up review status and authority:
+```
+
+Do not copy full reviewer output when a stable pointer exists. A new context or reviewer continues the existing budget; local edits, renamed scope, or a different reviewer do not reset it.
+
+## Resume Checklist
 
-- 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.
+- Reopen named source truth, the Working Record when present, and live worktree state.
+- Confirm artifact, environment, commit, and configuration identity where claims depend on them.
+- Verify important completion and evidence claims before repeating them.
+- Compare decisions, approval scope, review state, and the proposed route with live evidence.
+- Preserve valid context and identify only the invalidated layer.
+- Return the supported route and authority state to Workflow before editing.
+- Use Decision Gate for user-owned choices or source conflicts.

package/skills/launch-work/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: launch-work
+description: Use when preparing or carrying out a production deployment, rollout, rollback, or recovery.
+---
+
+# Launch Work
+
+Change production deliberately, observe the result, and preserve a safe recovery path.
+
+Deployment changes what runs. Rollout changes who or what is exposed. A build, merge, release, or staging pass does not prove production behavior.
+
+## Establish Authority And Boundary
+
+Loading this skill, preparing launch options, or approving a general implementation Plan does not authorize deployment, exposure, rollback, destructive migration, or another production action. Execute only the stages explicitly requested or separately approved through an inspected launch contract or accepted operational policy.
+
+Use [Decision Gate](../decision-gate/SKILL.md) when deployment, exposure, rollback, destructive migration, launch window, acceptable degradation, user communication, or recovery direction remains a user-owned choice.
+
+Read [launch readiness](references/launch-readiness.md) when selecting risk lenses, operational evidence, rollout stages, or recovery checks. Use [Release Work](../release-work/SKILL.md) when a versioned artifact must be published first. Use [Migration Work](../migration-work/SKILL.md) when the launch transitions data, traffic, consumers, configuration, or compatibility contracts between old and replacement paths with migration or removal obligations.
+
+## Define The Launch Contract
+
+Before changing production, establish:
+
+```text
+Outcome and affected users / systems:
+Artifact / commit / configuration identity:
+Target environment and owner:
+Deployment versus exposure stages:
+Dependencies and migration ordering:
+Expected technical, user, business, and data signals:
+Advance / hold / abort criteria:
+Rollback or forward-recovery path:
+Observation and post-launch verification:
+Communication and escalation:
+Approved stages and scope:
+```
+
+Use thresholds and observation periods supported by SLOs, baselines, policy, or explicit owner decisions. Do not import universal canary percentages, fixed windows, or “every feature needs a flag” rules.
+
+## Establish Readiness
+
+Select evidence for the actual production boundary. Relevant concerns may include:
+
+- accepted behavior and regression evidence;
+- security, privacy, permissions, billing, and data safety;
+- compatibility and migration readiness;
+- capacity, performance, dependency, and failure behavior;
+- configuration, secrets, infrastructure, and environment drift;
+- accessibility and critical user paths;
+- logs, metrics, traces, dashboards, alerts, and runbooks;
+- support, communication, ownership, and recovery authority.
+
+A concern is required only when its risk applies. Missing required evidence is not green. Confirm the intended artifact and configuration identity, required pre-production checks, recovery path, operational signals, and any selected review before starting an approved production stage.
+
+Read [Verify Work](../verify-work/SKILL.md) to match readiness claims to fresh direct evidence. Do not deploy merely to obtain evidence that should exist safely before production. When only production can answer a question, define an approved bounded learning rollout with observation, hold, abort, and recovery conditions first.
+
+Return unresolved owner decisions, material evidence gaps, or broader review needs to [Workflow](../workflow/SKILL.md). This skill defines the production boundary and evidence; Workflow owns routing and review selection.
+
+## Deploy And Expose In Approved Stages
+
+Separate operations when the platform permits it:
+
+- deploy inert code, configuration, or infrastructure;
+- verify health and compatibility;
+- expose a bounded cohort, tenant, region, or traffic segment;
+- compare required signals with the accepted baseline;
+- advance, hold, abort, roll back, or recover forward according to the contract.
+
+Feature flags, canaries, blue/green, shadow traffic, and phased regions are options, not defaults. Choose only mechanisms supported by the platform and accepted failure contract.
+
+For each approved stage:
+
+1. confirm artifact, configuration, target, and current production state;
+2. execute the bounded action once;
+3. verify technical and user-visible behavior;
+4. inspect telemetry, data integrity, and unexpected side effects;
+5. preserve anomalies and choose the next route before expanding exposure.
+
+Do not continue because elapsed time passed while required signals are missing. Approval of one stage does not authorize the next unless the accepted launch contract already does so.
+
+## Handle Failure And Recovery
+
+Hold or abort when accepted safety, data, security, compatibility, or service criteria are violated.
+
+Before rollback, determine whether code, schema, data, messages, caches, clients, or external effects make rollback unsafe or incomplete. Forward recovery may be safer, but it is not automatic permission to broaden scope.
+
+If production state is ambiguous, inspect the target before retrying. Do not repeat migrations, jobs, publishes, configuration changes, or exposure operations blindly.
+
+Use [Diagnose Failure](../diagnose-failure/SKILL.md) for unexpected behavior without a supported cause. Preserve incident evidence. Do not weaken alerts, checks, thresholds, or accepted behavior merely to declare the launch healthy.
+
+## Verify The Production Outcome
+
+Observe from the production boundary as applicable:
+
+- intended artifact and configuration are active;
+- critical user and failure paths behave as accepted;
+- data, compatibility, privacy, and permission invariants hold;
+- telemetry is present, queryable, bounded, and free of unexpected sensitive data;
+- alerts, escalation, and recovery routes work where required;
+- temporary flags, adapters, dashboards, elevated logging, permissions, or support procedures have owners and cleanup conditions.
+
+A quiet dashboard is not evidence when telemetry is absent or broken. State production paths, cohorts, observation windows, or recovery behavior that remain unverified.
+
+## Report Completion Precisely
+
+Report:
+
+- approved launch stage and exposure state;
+- deployed artifact, configuration, and target identity;
+- readiness evidence and owner decisions;
+- stage results and technical, user, business, and data observations;
+- holds, incidents, deviations, rollback, or forward recovery;
+- temporary machinery, owner, and cleanup condition;
+- residual risk and next approved observation, advance, cleanup, or stop route.
+
+Launch completion means the accepted production exposure and observation contract is satisfied—not merely that a deployment command succeeded. A completed launch does not authorize later migration removal, release publication, or cleanup outside the approved scope.

package/skills/launch-work/references/launch-readiness.md

@@ -0,0 +1,85 @@
+# Launch Readiness
+
+Use only the lenses relevant to the production change. This is not a universal checklist.
+
+## Identity And Ownership
+
+- Exact artifact, commit, image, configuration, migration, and target environment are known.
+- Deployment, rollout, rollback, incident, and communication owners are known where risk requires them.
+- Production permissions and credentials are available through approved channels without entering prompts, logs, or source.
+
+## Behavior And Compatibility
+
+- Accepted requirements and critical user paths have fresh evidence.
+- Public APIs, clients, schemas, feature states, and supported versions remain compatible or have an approved migration.
+- Failure, retry, idempotency, duplicate, ordering, and recovery behavior are settled for consequential operations.
+
+## Data And Migration
+
+- Authoritative source and migration ordering are explicit.
+- Backups, reconciliation, partial failure, restart, rollback, and forward-recovery behavior are proved to the required level.
+- Privacy, retention, deletion, audit, and permission obligations remain satisfied.
+
+## Security And Access
+
+- Threat-relevant changes received the required specialist or policy review.
+- Authentication, authorization, secret handling, untrusted input, dependency, network, and privilege boundaries are verified where affected.
+- Telemetry and support tooling do not expose secrets or unnecessary personal data.
+
+When Workflow selects a security-focused review, read the [security risk lens](../../review-work/references/security-risk-lens.md).
+
+## Performance And Capacity
+
+- Representative baseline and expected load are known where capacity can change.
+- Critical latency, throughput, saturation, queue, storage, and dependency limits have evidence.
+- Advance and abort criteria are relative to accepted SLOs, historical baseline, or owner-approved thresholds.
+
+Read [performance evidence](../../verify-work/references/performance-evidence.md) for readiness and improvement claims. Read [flaky and performance diagnosis](../../diagnose-failure/references/flaky-and-performance.md) only when a regression lacks a supported cause.
+
+## Accessibility And User Experience
+
+When user interfaces change, verify the affected critical paths using the repo's design/accessibility authority and available domain tooling. Consider keyboard, focus, semantics, assistive technology, responsive behavior, loading, empty, error, and degraded states only where relevant.
+
+## Observability
+
+Start from questions operators must answer:
+
+- Is the new path being used?
+- Is it succeeding and within accepted latency/capacity bounds?
+- Why is a specific request, job, or migration failing?
+- Are data, queues, retries, and dependencies healthy?
+- Can one affected operation be correlated across components?
+
+Choose structured logs for event detail, metrics for aggregate rate/error/duration or resource saturation, and traces for cross-component paths. Keep metric dimensions bounded. Do not log secrets, tokens, full sensitive payloads, or unrestricted personal identifiers.
+
+Verify telemetry itself by inducing or observing a safe known event, finding the signal, checking fields/labels, and confirming alert/runbook routing where required.
+
+## CI/CD And Environment
+
+- The pipeline and target environment execute the checks required by this change.
+- Generated artifacts are promoted consistently rather than rebuilt differently without approval.
+- Environment drift, secrets, migrations, and deployment ordering are inspected.
+- A failed or ambiguous pipeline step has a known retry/reconciliation contract.
+
+Provider-specific workflow syntax belongs to the repo or platform skill.
+
+## Rollout And Recovery
+
+Define:
+
+```text
+Stage / cohort:
+Action:
+Expected signals:
+Advance if:
+Hold if:
+Abort or recover if:
+Verification:
+Owner:
+```
+
+Rollback must account for code, data, schema, messages, clients, caches, and external side effects. Test or rehearse the recovery path to the level warranted by risk.
+
+## Temporary Machinery
+
+Flags, adapters, dual writes, elevated logging, launch dashboards, temporary permissions, and support procedures need an owner and cleanup checkpoint. Route compatibility removal through [Migration Work](../../migration-work/SKILL.md).

package/skills/migration-work/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: migration-work
+description: Use when replacing an existing software or data path and moving its consumers, state, or traffic safely.
+---
+
+# Migration Work
+
+Move consumers, state, or traffic to an accepted replacement without losing compatibility, evidence, or recovery options.
+
+A replacement existing does not prove that consumers moved. A migration unit may be complete while the old path remains under an accepted support contract. Removal is a separate claim with separate evidence and authority.
+
+## Establish Authority And Scope
+
+Loading this skill, discussing a migration, or approving a general implementation Plan does not authorize migration, deprecation, cutover, destructive cleanup, or removal. Execute only the stages and units explicitly requested or separately approved.
+
+Use [Decision Gate](../decision-gate/SKILL.md) when any of these remain unresolved:
+
+- whether the old behavior should be maintained, deprecated, or removed;
+- advisory versus compulsory migration, deadlines, or support windows;
+- compatibility, public API, data conversion, downtime, permissions, billing, security, privacy, or data-loss behavior;
+- irreversible cutover, destructive cleanup, or rollback limits.
+
+Do not manufacture a migration because code looks old. Inspect ownership, supported consumers, runtime use, source truth, incidents, maintenance cost, and current value.
+
+When replacement behavior, interfaces, ownership, or failure semantics remain unsettled, return that evidence to [Workflow](../workflow/SKILL.md). Use [Discuss](../discuss/SKILL.md) for open direction, [Design for Depth](../design-for-depth/SKILL.md) for design-bearing boundaries, and [Write Spec](../write-spec/SKILL.md) when accepted migration behavior needs a durable contract.
+
+## Define The Migration Contract
+
+Before moving anything, establish:
+
+```text
+Old contract and current value:
+Replacement contract and known differences:
+Consumers / callers / data / traffic:
+Compatibility promise and support window:
+Migration unit and ordering:
+State written during transition:
+Verification for each unit:
+Rollback or forward-recovery path:
+Removal proof:
+Owner decisions and stop conditions:
+Approved stages and scope:
+```
+
+Read [the migration lifecycle](references/migration-lifecycle.md) when choosing an API, code, configuration, dependency, feature, traffic, or data shape. Use only the stages required by the accepted migration; do not force every migration through one sequence.
+
+Treat undocumented observable behavior as a possible consumer dependency until evidence says otherwise. Do not preserve every quirk automatically; surface consequential differences for decision.
+
+## Prepare The Replacement
+
+When an additive or replacement stage is approved:
+
+- prove the replacement through the real caller path or interface;
+- keep old and new ownership explicit;
+- add adapters, flags, aliases, translation, or dual reads/writes only when the migration contract requires them;
+- give temporary compatibility machinery an owner, purpose, failure behavior, exit condition, and removal evidence;
+- do not add features to the old path unless required for safety or an explicit support decision.
+
+If compatibility machinery starts spreading caller knowledge, public states, or exceptions, return the structural evidence to Workflow rather than building a second permanent system.
+
+An emergency migration without a viable replacement may be necessary for security or data safety, but it requires explicit owner direction, bounded impact, and a documented failure and recovery contract.
+
+## Move Bounded Units
+
+Move one accepted consumer, cohort, traffic segment, configuration set, or data partition at a time.
+
+For each unit:
+
+1. capture the relevant pre-migration state or baseline;
+2. apply the migration through the intended path;
+3. verify behavior, data, errors, permissions, and operational signals at the required boundary;
+4. confirm rollback or forward recovery remains possible;
+5. preserve evidence and account for remaining units.
+
+Code search alone cannot prove completion when runtime, external, dormant, generated, offline, or independently deployed consumers may exist.
+
+Stop and return evidence to Workflow when replacement behavior diverges, unknown consumers appear, a new owner decision is required, data cannot be reconciled, recovery assumptions fail, compatibility machinery spreads, or the next safe unit is unclear. Preserve completed units; do not restart the whole migration automatically.
+
+## Remove The Old Path
+
+Remove or disable the old path only when that stage is explicitly authorized and the accepted removal proof is satisfied.
+
+Check, as relevant:
+
+- supported active and dormant consumers are accounted for;
+- runtime, telemetry, dependency, or owner evidence supports the absence claim;
+- data and configuration are reconciled;
+- compatibility, support-window, observation, and recovery obligations have ended;
+- old code, adapters, flags, tests, docs, alerts, dashboards, secrets, jobs, and configuration are classified for removal or retention;
+- the replacement remains verified with the old path disabled or absent.
+
+Do not delete source truth or historical migration evidence merely to make searches clean. If current docs or contracts would become false, return them to Workflow and update them only when they are included in the approved migration or removal scope. Preserve durable history where repository policy requires it.
+
+## Verification And Review
+
+Read [Verify Work](../verify-work/SKILL.md) for each migration-unit, compatibility, reconciliation, and absence claim. “The new path passes” does not prove “the old path is unused.” Missing telemetry is unavailable evidence, not zero use.
+
+Return the need for broader judgment to Workflow when the migration changes public contracts, moves consequential data, crosses security or privacy boundaries, affects many consumers, or performs irreversible cutover or cleanup. Workflow selects any independent review; this skill supplies the migration boundary and evidence.
+
+Use [Release Work](../release-work/SKILL.md) when the replacement must be published as a versioned artifact. Use [Launch Work](../launch-work/SKILL.md) when migration stages change production traffic, data, configuration, or exposure.
+
+## Report Completion Precisely
+
+Report:
+
+- approved migration scope and completed units;
+- replacement and compatibility status;
+- remaining consumers, state, traffic, or observation windows;
+- verification and operational evidence;
+- rollback or forward-recovery status;
+- legacy components removed and deliberately retained;
+- unresolved decisions, uncertainty, and residual risk;
+- next approved unit, removal boundary, deferment, or stop route.
+
+A migration unit is complete when its accepted consumers or state moved and its required evidence holds. A scoped migration may complete while the legacy path remains under an accepted support contract. Removal is complete only when its separate authorization and proof are satisfied.

package/skills/migration-work/references/migration-lifecycle.md

@@ -0,0 +1,82 @@
+# Migration Lifecycle
+
+Read this when choosing migration units, compatibility shape, cutover evidence, rollback, or removal proof.
+
+## Migration Shapes
+
+- **Code or API:** add the new contract, migrate callers in bounded groups, remove the old contract.
+- **Configuration:** support old and new forms temporarily, migrate stored and generated config, reject the old form only after compatibility obligations end.
+- **Traffic:** route bounded cohorts to the new path, compare behavior and operational signals, expand only when advance criteria hold.
+- **Data:** expand schema, backfill or transform, move reads/writes, reconcile, then contract the old representation.
+- **Dependency:** introduce the replacement, verify compatibility at owning seams, migrate packages or consumers, remove the old dependency and transitive assumptions.
+- **Feature:** define replacement or removal behavior, migrate users and documentation, observe usage, then remove code and operational surfaces.
+
+Do not force every migration into the same sequence. Choose the smallest shape that preserves accepted compatibility, safety, and evidence. A scoped migration may stop after its accepted units move while the old contract remains under a support window; removal remains a separate stage and claim.
+
+## Consumer Inventory
+
+Possible evidence includes:
+
+- static references and dependency graphs;
+- runtime traffic, logs, metrics, traces, or audit records;
+- generated clients, plugins, scripts, jobs, and configuration;
+- external teams, independently deployed services, offline clients, and dormant accounts;
+- package download or version-support data;
+- explicit owner attestations where observation is impossible.
+
+Classify unknowns. Missing telemetry is unavailable evidence, not zero usage.
+
+## Compatibility Machinery
+
+Adapters, aliases, dual reads/writes, translation, flags, and shims are migration tools, not automatically permanent architecture.
+
+For each temporary mechanism, record:
+
+```text
+Purpose:
+Consumers protected:
+Observable differences:
+Owner:
+Exit condition:
+Removal evidence:
+Failure behavior:
+```
+
+If the shim becomes harder to remove with each consumer, reconsider the compatibility boundary and ownership before adding another exception.
+
+## Data Movement
+
+Before moving data, settle:
+
+- authoritative source during each phase;
+- idempotency and restart behavior;
+- duplicate, partial, invalid, and late-arriving records;
+- read/write ordering and reconciliation;
+- privacy, retention, permissions, and audit requirements;
+- rollback versus forward-only recovery;
+- backup, restore, and destructive-cleanup proof.
+
+A reversible schema change does not imply reversible data semantics.
+
+## Advance, Hold, Roll Back
+
+Define evidence-relative criteria rather than universal percentages or time windows:
+
+- **Advance:** required behavior and operational signals remain within accepted bounds.
+- **Hold:** evidence is incomplete, variance is unresolved, or a bounded investigation is needed.
+- **Roll back or recover forward:** data safety, security, compatibility, or accepted service behavior is violated.
+
+The owner decides consequential thresholds and acceptable degradation.
+
+## Removal Proof
+
+A removal claim should combine the strongest available evidence:
+
+1. no supported consumer still requires the old contract;
+2. runtime or owner evidence covers consumers static analysis cannot see;
+3. state and configuration have been reconciled;
+4. compatibility and rollback obligations have ended;
+5. the replacement remains verified with the old path disabled or absent;
+6. removal does not erase required history, audit evidence, or recovery material.
+
+If a consumer class cannot be observed, state the uncertainty and obtain the owning decision before destructive removal.