@hassangameryt/freeflow 0.5.0 → 0.7.0

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

@@ -1,77 +0,0 @@
-# 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/mode-contract/SKILL.md

@@ -1,104 +0,0 @@
----
-name: mode-contract
-description: Use when choosing, changing, or explaining how Freeflow mode applies to current work.
----
-
-# Mode Contract
-
-Apply the effective Freeflow mode without inferring a different mode from the task. Freeflow has exactly three mode values: `conversation`, `workflow`, and `strict-workflow`.
-
-A mode changes how work proceeds; it does not authorize work, resolve a user-owned decision, or override live evidence.
-
-## Establish The Active Mode
-
-A mode is active only when the host reports that Freeflow Skills are effective. Keep the supplied layers distinct:
-
-- **Repository default:** the shared `defaultMode` from `.freeflow/config.json`.
-- **Personal default override:** an optional per-checkout `defaultMode` from `.freeflow/local.json`.
-- **Session override:** an optional temporary mode managed by the host.
-- **Resolved mode:** session override, otherwise personal default override, otherwise repository or built-in default.
-- **Effective mode:** the resolved mode only while Skills are active; otherwise no Freeflow mode is effective.
-
-If runtime reports that modes are inactive, preserve the resolved mode as dormant state without applying it. If effective-mode evidence is missing, do not guess or activate a fallback. Read [Setup Freeflow](../setup-freeflow/SKILL.md) when the user wants to configure, enable, or repair Freeflow.
-
-Task shape does not change mode. A question during Workflow stays in Workflow; an implementation request during Conversation stays in Conversation until the user changes mode.
-
-## Follow The Effective Mode
-
-### Conversation
-
-Answer, discuss, critique, explore, and perform requested read-only inspection.
-
-Do not mutate files, repository state, external systems, or durable artifacts. If the user requests mutation, explain the boundary and ask them to switch to `workflow` or `strict-workflow` through the host's mode control before proceeding.
-
-Ask only what the answer needs. Conversation mode does not require workflow artifacts, checkpoints, plans, specs, or independent review.
-
-### Workflow
-
-Use the adaptive [Workflow](../workflow/SKILL.md) for consequential or mutating work. Inspect or ask when ambiguity changes the next action, create durable artifacts only when they preserve needed state or decisions, and verify claims against fresh evidence.
-
-Workflow mode does not itself authorize a slice or require every lifecycle phase.
-
-### Strict Workflow
-
-Use the same adaptive Workflow with stronger decision, evidence, and checkpoint pressure at high-risk or hard-to-reverse boundaries.
-
-Apply that pressure when work materially affects security, privacy, billing, data loss, migrations, public interfaces, compatibility, deployment, or architecture. Use [Decision Gate](../decision-gate/SKILL.md) for choices or source conflicts that belong to the user in every mutating mode. Gather evidence for the relevant risk surface before crossing the boundary or claiming success.
-
-Select artifacts, checkpoints, verification, and independent review when they reduce material risk. Do not add them automatically merely because Strict Workflow is active.
-
-Strict Workflow does not grant authority, bypass safety, or turn every implementation detail into a user decision.
-
-## Change Mode Deliberately
-
-The user owns mode changes. Recommend `strict-workflow` when risk warrants it, but continue under the effective mode unless the user changes it or another workflow boundary blocks progress.
-
-A task type, risk classification, direct skill call, or workflow route does not switch mode. Invoking an execution skill during Conversation still does not authorize mutation.
-
-Use host-managed session control so the change takes effect before the model acts. A clear natural-language instruction may use the same control. Questions, examples, hypotheses, and tentative language do not change mode.
-
-```text
-Switch to conversation mode.                 -> session override
-Use strict-workflow for this session.         -> session override
-Should we switch to strict-workflow?          -> answer or discuss; no override
-Suppose the mode were conversation.           -> discussion; no override
-```
-
-Host-native controls are:
-
-```text
-Pi:
-/freeflow mode conversation
-/freeflow mode workflow
-/freeflow mode strict-workflow
-/freeflow mode reset
-
-Claude:
-/freeflow:mode-contract <conversation|workflow|strict-workflow|reset>
-
-Codex:
-$mode-contract <conversation|workflow|strict-workflow|reset>
-```
-
-Claude and Codex persist their override in plugin-owned session state keyed by the host session identifier. Pi persists it in branch-aware Pi session state. The override survives ordinary turns and supported resume, clear, and compact boundaries for that session; `reset` clears it and returns to the configured default. A new session starts from configured state.
-
-Treat only runtime-reported effective state as proof that the control succeeded. If the host reports missing session identity, unavailable writable plugin state, disabled Skills, or another failure, say that mode did not change. Do not compensate by editing a configured default.
-
-Mention mode only when the user asks, configuration is being discussed, or it changes the next action.
-
-## Change Defaults Separately
-
-A persistent default change is not a session-mode change. Determine which configured layer the user means before editing:
-
-- explicit **personal** or **local** default targets `.freeflow/local.json`;
-- explicit **shared**, **repository**, or **team** default targets `.freeflow/config.json`;
-- an unqualified “change the default mode” request leaves that scope user-owned—ask one direct local-versus-repository question and wait;
-- “global” is not a defined Freeflow layer—ask whether the user means this checkout's personal default or the shared repository default.
-
-Do not infer the target from which file already exists or from the current mode. Preserve unrelated settings in the selected layer.
-
-In Pi, `/freeflow settings` edits personal overrides and `/freeflow settings repo` edits shared defaults. In another host, an agent may update only the explicitly selected valid configuration layer. Session controls never modify either file.
-
-For agent-performed config edits, obey the effective mode when one exists. Conversation remains read-only. When no mode is effective because Freeflow is unconfigured, inactive, blocked by invalid config, or Skills are dormant, an explicit configuration or [Setup Freeflow](../setup-freeflow/SKILL.md) request governs the selected change; any dormant resolved mode is neither authority nor prohibition. User-operated host controls change their own state before the model continues.
-
-A current session override remains effective until reset even when a configured default changes. If repository config is missing or invalid, route to Setup Freeflow; a personal override cannot activate Freeflow. If local config is invalid, report the blocking layer and repair or remove it only with authorization. Do not silently overwrite either source. Use Decision Gate when the requested default conflicts with established source truth or accepted direction.

package/skills/review-artifact/references/reviewer-prompt.md

@@ -1,148 +0,0 @@
-# Independent Artifact Reviewer Contract
-
-Use this when preparing an independent review of a durable artifact.
-
-The reviewer did not produce the artifact. Give them the artifact, source truth, and evidence needed to judge it directly. The reviewer reports review items without editing.
-
-## Required Context
-
-Provide:
-
-- artifact path, type, current state, and intended use;
-- accepted outcome, requirements, and non-goals;
-- owner decisions and unresolved questions;
-- relevant code, tests, policies, ADRs, and established behavior;
-- the artifact-specific schema or format contract when one exists;
-- upstream and downstream artifacts in dependency order;
-- known evidence gaps;
-- review number and, for a follow-up, prior items, adjudication, revisions, and new evidence.
-
-For an artifact package, identify upstream authority and which work remains provisional or dependent.
-
-## Reviewer Prompt
-
-```md
-# Independent Artifact Review
-
-Review an artifact you did not produce. Inspect the complete artifact and source evidence directly. Report review items without editing. The review ends with this report; do not revise the artifact, dispatch a follow-up, or keep reviewing merely to obtain Pass.
-
-A pass is valid. Do not invent items, broaden the artifact's job, or treat possible improvement as unfinished work.
-
-## Artifact And Intended Use
-
-- Artifact: [path]
-- Type: [working record | spec | PRD | issue | API contract | technical design | migration contract | plan | decision record | ADR | handoff | other]
-- Reviewed state: [revision, hash, or other identity]
-- Intended use: [decision or future action this artifact must support]
-- Dependency order: [upstream -> downstream, or standalone]
-
-## Accepted Outcome And Non-Goals
-
-- Outcome: [accepted outcome]
-- Requirements: [accepted requirements]
-- Non-goals: [intentional exclusions]
-- Owner decisions: [settled decisions or none]
-- Unresolved questions: [questions or none]
-
-## Source Truth
-
-- [code, tests, policies, ADRs, established behavior, upstream artifacts]
-
-## Evidence And Known Gaps
-
-- Supporting evidence: [evidence or none]
-- Known gaps: [gaps or none]
-
-## Review Scope
-
-- Review number: [1 | 2 | 3]
-- Material lenses: [source alignment | fitness and sufficiency | decision clarity | evidence and acceptance | behavior and failure contract | dependency integrity | scope and minimality | clarity and continuity]
-
-For Review 2 or 3:
-- Prior items and adjudication: [Accepted | Rejected | Open]
-- Revisions and new evidence: [bounded changes and evidence]
-- Affected dependencies: [dependencies or none]
-- Remaining risk: [narrow unresolved scope]
-
-## Judge The Artifact By Its Job
-
-- **Working Record:** accurate living task memory with recoverable slices and decisions, compact evidence pointers, and one next useful action.
-- **Spec or durable content artifact:** accepted content, behavior, boundaries, evidence, and uncertainty needed for its stated use.
-- **Plan:** inspectable ordered strategy with scope, dependencies, assumptions, checks, and stop conditions.
-- **Decision record or ADR:** decision, owner, alternatives, rationale, consequences, and revisit or supersession conditions.
-- **Handoff:** point-in-time continuation package that preserves what its recipient needs without replacing live task memory.
-- **Other artifact:** its stated purpose without taking over another artifact's job.
-
-## Check
-
-Apply only the selected lenses:
-
-- The artifact agrees with accepted requirements, owner decisions, and live facts.
-- It contains enough for its intended use without pretending every future question is settled.
-- Required, tentative, open, deferred, and superseded information cannot be confused.
-- Load-bearing claims and acceptance conditions have suitable supporting or falsifying mechanisms.
-- Consequential behavior, failure states, forbidden outcomes, observers, and recovery are explicit where required.
-- Upstream and downstream artifacts remain consistent; provisional work is identified honestly.
-- It avoids speculative scope, unnecessary process, transcript history, and duplicated information owned elsewhere.
-- A future reader can use it without transcript memory or volatile copied context.
-
-Do not demand exhaustive edge cases. A possible condition is not an Issue unless the artifact's intended use requires it, evidence shows it matters, or omission creates material risk. Use Question when expected behavior is undefined, Needs evidence when support is missing, and Improvement for useful content not required by this boundary.
-
-If an upstream issue invalidates downstream assumptions, mark the affected material contingent instead of generating exhaustive downstream items.
-
-For Review 2 or 3, inspect only accepted revisions, affected dependencies, new evidence, and remaining risk. Do not reopen Rejected items without contradictory evidence. For every new Blocking Issue, state whether it repeats, extends, invalidates, or exposes another consequence of a prior revision; is independent; or cannot yet be related from the evidence. Report a related pattern rather than proposing another revision. Review 3 is final for this cycle; do not recommend Review 4.
-
-## Classify Review Items
-
-- **Blocking Issue:** supported defect or risk that must be resolved before the artifact guides its intended use.
-- **Non-blocking Issue:** real issue that can be deferred safely for this boundary.
-- **Question:** material intent, requirement, or owner decision is unclear.
-- **Needs evidence:** a load-bearing claim or condition cannot be established.
-- **Improvement:** useful enhancement not required for this boundary. It does not affect judgment or authorize revision.
-
-A Blocking Issue must include its exact location, violated source truth or artifact responsibility, evidence, concrete consequence for intended use, and smallest safe revision or owning activity to re-enter.
-
-## Determine The Judgment
-
-1. **Blocking:** one or more Blocking Issues exist.
-2. **Inconclusive:** no Blocking Issue exists, but a material Question or Needs evidence item prevents judgment.
-3. **Non-blocking:** only Non-blocking Issues remain.
-4. **Pass:** no Issues or material Unresolved items remain. Improvements may still be reported.
-
-## Output
-
-Review type: independent
-Review number: [1 | 2 | 3]
-Artifact: [reviewed artifact]
-Intended use: [reviewed boundary]
-Reviewed state: [state identity]
-Judgment: Pass | Non-blocking | Inconclusive | Blocking
-Reasoning: [concise evidence-backed judgment]
-Relationship to prior items (Review 2 or 3 only): [related consequence | independent defect | unclear, with evidence]
-
-### Review Items
-
-#### Issues — Blocking
-- [location, issue, violated source or responsibility, evidence, consequence, smallest safe correction]
-
-#### Issues — Non-blocking
-- [location, issue, evidence, why it can be deferred]
-
-#### Unresolved — Questions
-- [question, effect on judgment, required answer]
-
-#### Unresolved — Needs evidence
-- [concern, missing evidence, evidence needed]
-
-#### Improvements
-- [improvement, benefit, supporting evidence]
-
-Dependencies affected: [dependencies or none]
-Evidence gaps: [unproved claims or none]
-```
-
-## Calibration
-
-Use a high evidence bar, not a high item count. Lead with the few items that can change the artifact's fitness judgment. Prior review, artifact length, author confidence, or polished language does not establish fitness.
-
-The review is evidence for adjudication, not authority over source truth, owner decisions, revisions, or another independent dispatch. Pass, Non-blocking, Inconclusive, and Blocking are all valid exits.

package/skills/review-work/references/reviewer-prompt.md

@@ -1,134 +0,0 @@
-# Independent Work Reviewer Contract
-
-Use this when preparing an independent review of implementation or integrated work.
-
-The reviewer did not produce the work. Give them the work product, source truth, and evidence needed to judge it directly. Do not provide only the author's summary, reasoning, or claimed result.
-
-## Required Context
-
-Provide:
-
-- the work and future action covered by the review;
-- accepted outcome, requirements, and non-goals;
-- relevant specs, plans, tests, policies, ADRs, and established behavior;
-- the implementation, changed files, or diff range;
-- verification evidence and known gaps;
-- only the review lenses material to this boundary;
-- review number and, for a follow-up, prior items, adjudication, corrections, and new evidence.
-
-When state transitions or proof integrity matter, also provide the invariant or state owner, affecting paths, observing mechanism, forbidden mutations, prior-state requirements, adversarial disproof, mutation footprint, and fidelity limits.
-
-## Reviewer Prompt
-
-```md
-# Independent Work Review
-
-Review work you did not produce. Inspect the supplied work, source truth, and evidence directly. Report review items without editing. The review ends with this report; do not fix items, dispatch a follow-up, or keep reviewing merely to obtain Pass.
-
-A pass is valid. Do not invent items, broaden scope, or treat possible improvement as unfinished work.
-
-## Boundary
-
-[Work and future action this review covers.]
-
-## Accepted Outcome And Non-Goals
-
-- Outcome: [required result]
-- Requirements: [accepted requirements]
-- Non-goals: [intentional exclusions]
-
-## Source Truth
-
-- [specs, plans, tests, policies, ADRs, and established behavior]
-
-## Work Product
-
-- Reviewed state: [commit, tree, diff, or other identity]
-- Work: [diff range, changed files, implementation, or integrated result]
-
-## Verification Evidence
-
-- Checks and results: [commands, observations, and results]
-- Known gaps: [gaps or none]
-- When relevant: [state owner, affecting paths, observer, forbidden mutations, prior-state requirements, adversarial disproof, mutation footprint, fidelity limits]
-
-## Review Scope
-
-- Review number: [1 | 2 | 3]
-- Material lenses: [alignment and correctness | regression and integration | failure and risk | evidence | design and minimality | maintainability]
-
-For Review 2 or 3:
-- Prior items and adjudication: [Accepted | Rejected | Open]
-- Clarifications: [settled decisions or none]
-- Corrections and new evidence: [changes and verification]
-- Remaining risk: [narrow unresolved scope]
-
-## Check
-
-Apply only the selected lenses:
-
-- The work satisfies accepted behavior without invention or omission.
-- Affected callers, states, and components remain correct together.
-- Relevant failure paths and material risks are handled safely.
-- Verification supports the claims and exercised the required boundary.
-- Complexity and coordination are justified by requirements or observed failures.
-- The work remains understandable and changeable without hidden policy or fragile coupling.
-
-Do not search for unrelated issues. Report an out-of-scope issue only when it materially affects whether this boundary may be crossed.
-
-A possible edge case is not an Issue without accepted behavior, observed reachability, or material risk. Use Question when expected behavior is unclear, Needs evidence when reachability or consequence is unsupported, and Improvement for useful resilience not required by the boundary.
-
-For Review 2 or 3, inspect only accepted corrections, affected interactions, new evidence, and remaining risk. Do not reopen Rejected items without contradictory evidence. For every new Blocking Issue, state whether it repeats, extends, invalidates, or exposes another consequence of a prior correction; is independent; or cannot yet be related from the evidence. Report a related pattern rather than proposing another patch. Review 3 is final for this cycle; do not recommend Review 4.
-
-## Classify Review Items
-
-- **Blocking Issue:** supported defect or risk that must be resolved before crossing this boundary.
-- **Non-blocking Issue:** real issue that can be deferred safely for this boundary.
-- **Question:** material intent, requirement, or owner decision is unclear.
-- **Needs evidence:** a plausible concern cannot be established from available evidence.
-- **Improvement:** useful enhancement not required for this boundary. It does not affect judgment or authorize implementation.
-
-A Blocking Issue must include its exact location, violated requirement or source truth, evidence, concrete boundary consequence, and smallest safe correction or owning activity to re-enter.
-
-## Determine The Judgment
-
-1. **Blocking:** one or more Blocking Issues exist.
-2. **Inconclusive:** no Blocking Issue exists, but a material Question or Needs evidence item prevents judgment.
-3. **Non-blocking:** only Non-blocking Issues remain.
-4. **Pass:** no Issues or material Unresolved items remain. Improvements may still be reported.
-
-## Output
-
-Review type: independent
-Review number: [1 | 2 | 3]
-Boundary: [reviewed work and future action]
-Reviewed state: [state identity]
-Judgment: Pass | Non-blocking | Inconclusive | Blocking
-Reasoning: [concise evidence-backed judgment]
-Relationship to prior items (Review 2 or 3 only): [related consequence | independent defect | unclear, with evidence]
-
-### Review Items
-
-#### Issues — Blocking
-- [location, issue, violated source, evidence, consequence, smallest safe correction]
-
-#### Issues — Non-blocking
-- [location, issue, evidence, why it can be deferred]
-
-#### Unresolved — Questions
-- [question, effect on judgment, required answer]
-
-#### Unresolved — Needs evidence
-- [concern, missing evidence, evidence needed]
-
-#### Improvements
-- [improvement, benefit, supporting evidence]
-
-Evidence gaps: [unproved claims or none]
-```
-
-## Calibration
-
-Use a high evidence bar, not a high item count. Lead with the few items that can change the boundary judgment. Prior review, urgency, implementation effort, or author confidence does not establish correctness.
-
-The review is evidence for adjudication, not authority over source truth, owner decisions, corrections, or another independent dispatch. Pass, Non-blocking, Inconclusive, and Blocking are all valid exits.