@hassangameryt/freeflow 0.3.0 → 0.5.0

package/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 | Discover | 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/>discover / 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/skills/interview-gate/SKILL.md

@@ -1,90 +0,0 @@
----
-name: interview-gate
-description: Use when context is low, scope is ambiguous, implementation/review/verification reveals unknowns, the user asks a question or suggests a path that could be misread as correction/permission, or the agent may be about to make a user-owned decision.
----
-
-# Interview Gate
-
-Stop before silent decisions.
-
-Known material method substitutions are decision points. If the requested, planned, or skill-required method and the fallback are already known, ask before source inspection, fallback work, or report drafting. Do not inspect files merely to make the fallback response more precise.
-
-## Stop First: Question or Decision Point
-
-If the user asks a question, answer it. Do not treat the question as criticism, permission, or a request to change behavior. Do not create, update, or delete files.
-
-If the answer reveals missing work, report the gap. Do not fill it unless the user asks you to.
-
-When the user asks "why did you", "did you", "what happened", or similar, answer what happened and why. Do not infer scolding, apologize, revert, edit, or promise future behavior changes unless the user asks.
-
-When the user suggests "this is better, right", "shouldn't we", or a similar option, treat it as a hypothesis. Evaluate against evidence and say yes, no, or partly. Do not agree just to be agreeable.
-
-If adopting a suggestion would change scope, source truth, workflow, files, or user-visible behavior, ask before acting.
-
-If the user is deciding the next path, answer the decision first. Do not turn "should we", "do we need", "let's X before Y", or "what next" into file changes unless the action and destination are explicit.
-
-Existing practice is evidence, not approval. "We usually do X" does not authorize X when another live rule or destination would also fit.
-
-Fire this gate from any workflow state when the next action depends on:
-
-- Product behavior.
-- Scope or priority.
-- Domain meaning.
-- Artifact creation, destination, or durability.
-- Compatibility.
-- Public API or user-facing behavior.
-- Irreversible architecture.
-- Security, privacy, billing, or data-loss behavior.
-- Changing docs, tests, specs, policies, ADRs, or handoffs to fit a new implementation request.
-- A user request, handoff, plan, or review comment contradicts current repo evidence.
-- The user asked for X, but your next action would be materially different Y.
-- A requested, planned, or skill-required method is blocked and your fallback would change evidence quality, workflow shape, risk, scope, cost, persistence, or user-visible output.
-
-## Inspect Before Asking
-
-If the answer is discoverable, inspect first:
-
-- Code.
-- Tests.
-- Docs.
-- Logs.
-- Issues.
-- ADRs or decision records.
-- Current external docs when facts may have changed.
-
-Ask the user only for decisions that remain user-owned.
-
-## Conflict Pattern
-
-If the requested path conflicts with evidence, rules, constraints, or your intended next action:
-
-- Stop before acting.
-- Name the requested path and the conflicting path.
-- Name the blocking constraint.
-- Say why the difference changes the next action.
-- Ask which path to follow.
-- Give a recommendation when the evidence supports one.
-
-Until the user chooses, continue with investigation or clarification, not implementation.
-
-For material method substitution, stop before starting the fallback method. The constraint itself is enough to ask when the fallback would change evidence quality, workflow shape, confidence, or output.
-
-Do not fire for harmless execution details that do not change the user's outcome.
-
-Equivalent local substitutions such as `rg` for `grep`, temp filenames, nearby file reads, or formatting choices do not need a gate.
-
-## Question Pattern
-
-Ask one question at a time.
-
-For each question:
-
-- State the uncertainty.
-- Explain why it changes the next action.
-- Give your recommended answer when possible.
-
-Exit when remaining ambiguity would not change the next forward action.
-
-## Backward Flow
-
-When implementation, review, or verification reveals a gap, return here before changing direction. Do not patch forward silently.

package/skills/setup-freeflow/references/output-router-setup.md

@@ -1,102 +0,0 @@
-# Output Router Setup
-
-Use this when setup reaches the optional capabilities branch or explicitly asks for output-router, observed-routing, generated-path, native safety-net, vault, threshold, script-transform adapters, or script-transform repo config (`scriptTransform`).
-
-## Defaults
-
-- The output router has built-in defaults. A repo does not need optional config for normal search/run/transform behavior.
-- Minimal `/setup-freeflow` must still write only `defaultMode`.
-- Ask one capabilities decision point. If declined, do not write `outputRouter`, `observedRouting`, or `scriptTransform`, and do not install script adapters.
-- Observed routing is opt-in per producer/server. The user must choose persistence for each enabled entry before setup writes config.
-- Do not create a separate `setup-output-router` skill.
-
-If the user says only “set up the output router” with no requested knobs, say the router works with built-in defaults and ask which optional config they want persisted. Recommend no repo config unless they need observed routing, repo-specific hints, script transform setup, or safety-net behavior.
-
-## Config Shape
-
-Write only keys the user explicitly requests. Do not dump all defaults and do not create empty `outputRouter`, `observedRouting`, or `scriptTransform` objects. Do not write removed `capture` or `providers` config.
-
-Supported high-level repo config keys:
-
-```json
-{
-  "defaultMode": "workflow",
-  "outputRouter": {
-    "enabled": true,
-    "profile": "standard",
-    "postToolRouting": "off",
-    "largeOutputBytes": 64000,
-    "largeOutputLines": 1000,
-    "vaultRoot": "~/.cache/freeflow-router/vault",
-    "vaultRetentionDays": 7,
-    "generatedPaths": ["graphify-out/**"],
-    "noisyCommandHints": ["npm test"]
-  },
-  "observedRouting": {
-    "enabled": true,
-    "onRoutingFailure": "fail-open",
-    "mcp": {
-      "servers": {
-        "github": { "enabled": true, "persistence": "exact" },
-        "gmail": { "enabled": true, "persistence": "metadata-only" }
-      }
-    },
-    "web": { "enabled": true, "persistence": "exact" },
-    "fetch": { "enabled": true, "persistence": "exact" },
-    "codeSearch": { "enabled": true, "persistence": "exact" }
-  },
-  "scriptTransform": {
-    "enabled": true,
-    "sandbox": "auto",
-    "languages": ["javascript", "python", "jq"],
-    "network": "off",
-    "limits": {
-      "timeoutMs": 5000,
-      "maxInputBytes": 1048576,
-      "maxOutputBytes": 65536
-    },
-    "rawScriptPersistence": "disabled"
-  }
-}
-```
-
-Rules:
-
-- `outputRouter.enabled` defaults to `true`; write it only as an intentional high-level decision.
-- `outputRouter.profile` currently supports `standard`; write it only when the user chooses the evidence-routing branch.
-- `postToolRouting` defaults to `off`. Use `safety-net` only when explicitly requested. Treat `strict` as reserved; ask before writing it.
-- `largeOutputBytes`, `largeOutputLines`, and `vaultRetentionDays` must be positive integers.
-- `vaultRoot` must be a non-empty string. Repo-local storage requires explicit user choice.
-- `generatedPaths` are broad-scan generated-path hints. Explicit file or directory retrieval must remain available.
-- `noisyCommandHints` is parsed as hint config. Do not add it unless the user explicitly asks for command-pattern hints.
-- `observedRouting.enabled` defaults to `false`; write it only when the user chooses observed routing.
-- `observedRouting.onRoutingFailure` currently supports `fail-open`; write it only when persisting observed routing.
-- `observedRouting.mcp.servers` must contain explicit server entries only. Setup may discover configured servers for a multi-select, but must not persist a volatile inventory of every installed tool.
-- `observedRouting.web`, `observedRouting.fetch`, and `observedRouting.codeSearch` are Pi observed-routing producers. Enable only the producers the user chose.
-- Every enabled observed-routing entry needs a user-chosen persistence mode: `exact`, `metadata-only`, or `none`.
-- Recommend `exact` for public-ish evidence producers such as GitHub, web, fetch, and code search. Recommend `metadata-only` for sensitive or unknown producers such as Gmail, Slack, private customer systems, or likely-secret outputs.
-- Do not offer or write `redacted`; it is reserved for future work and currently falls back to `metadata-only` with a warning if hand-edited.
-- Pi public `freeflow_capture` and the separate `providers` setup surface have been removed. Do not write removed `capture` or `providers` config.
-- `scriptTransform.enabled` defaults to `false`; write it only after an explicit script-execution opt-in.
-- If the user opts into script transform setup and adapters are missing or unavailable, recommend installing global adapters. On consent, resolve `../../router/dist/setup/script-transform-adapters.js` relative to `skills/setup-freeflow/SKILL.md` and run `node <plugin-root>/router/dist/setup/script-transform-adapters.js install --config .freeflow/config.json`.
-- The installer uses `~/.cache/freeflow-script-adapters` by default, or `FREEFLOW_SCRIPT_TRANSFORM_ADAPTERS_HOME` when set. It installs `quickjs-wasi@3.0.1`, `jq-wasm@1.2.0-jq-1.8.2`, `@bsull/eryx@0.5.0`, and `node@24` for the Python JSPI child runner, writes `freeflow-adapter-env.sh`, probes sandbox proofs, and updates `scriptTransform.languages` with only proof-passing languages.
-- Freeflow auto-discovers adapters from that global cache. The explicit roots `FREEFLOW_QUICKJS_WASI_ROOT`, `FREEFLOW_JQ_WASM_ROOT`, and `FREEFLOW_ERYX_ROOT` remain overrides for custom installs.
-- Python/Eryx is installed by setup and uses the setup-installed child Node process launched with `--experimental-wasm-jspi` when the host process lacks JSPI. It must not be marked available unless that child runner passes the required sandbox probes.
-- `scriptTransform.languages` supports `javascript`, `python`, and `jq`; enable only languages whose adapters passed sandbox proofs.
-- `scriptTransform.sandbox` currently supports `auto`, `network` supports only `off`, and `rawScriptPersistence` supports only `disabled`.
-- `scriptTransform.limits.timeoutMs`, `maxInputBytes`, and `maxOutputBytes` must be positive integers within product caps. Per-call script limits may only tighten configured values.
-
-## Verify
-
-After writing optional evidence-routing config, use `freeflow_status` or equivalent direct inspection to verify effective behavior:
-
-- JSON parses.
-- `defaultMode` is valid.
-- Minimal setup still contains only `defaultMode` when capabilities were declined.
-- Optional `outputRouter`, `observedRouting`, and `scriptTransform` sections contain only requested keys.
-- Invalid router/observed-routing/script-transform values are not written.
-- Observed routing, native safety-net routing, and script transform are not enabled unless explicitly requested.
-- If script transform setup was accepted, global adapter install completed or a clear install/probe failure was reported, and enabled languages match proof-passing adapters.
-- No observed-routing entry uses `redacted`, and every enabled entry has explicit persistence.
-- `freeflow_status` shows effective defaults and migration recommendations without rewriting config.
-- No repo-local hooks, skill files, setup-output-router skill, docs inventories, or repo-local storage directories were created.

package/skills/workflow/references/workflow-map.md

@@ -1,104 +0,0 @@
-# Freeflow Map
-
-Use this when the user asks how the whole workflow fits together, public docs need a diagram, or the next workflow entry point is unclear.
-
-This map is orienting, not mandatory. Small reversible work can skip unnecessary artifacts and gates. Re-enter clarification whenever new ambiguity would change the next action.
-
-## Compact Map
-
-Use this compact version in public README-style docs.
-
-```mermaid
-flowchart LR
-  Request{request}
-  Talk[conversation<br/>answer directly]
-  Discover[discover<br/>checkpoint]
-  Spec[spec]
-  Plan[plan]
-  Build[build<br/>execute / diagnose / TDD]
-  Check[review + verify]
-  Close[commit / handoff]
-
-  Request -->|question| Talk
-  Request -->|work| Discover
-  Discover --> Spec --> Plan --> Build --> Check --> Close
-  Check -. new evidence or failed check .-> Discover
-```
-
-```text
-Use conversation mode for non-mutating questions, critique, read-only exploration, and planning in chat. Use workflow mode for edits, file creation, mutating commands, or other consequential work.
-Use strict-workflow for risky work; same spine, stronger gates.
-Loop back when new evidence, source conflicts, user-owned decisions, or failed checks change the path.
-Use `Next:` when a response leaves a useful next route. Completed consequential phases should close with forward, backward, branch, or stop unless the reply is only an answer, status update, clarification, or direct owner-decision question.
-```
-
-## Reference Map
-
-Use this fuller version when choosing an entry point or explaining the workflow lifecycle.
-
-```mermaid
-flowchart TD
-  Request([User request]) --> Mode{Mode}
-
-  Mode -->|question, critique, explanation| Conversation[conversation mode<br/>answer directly]
-  Conversation --> Done([done])
-
-  Mode -->|consequential work| Workflow[workflow mode<br/>scale to risk]
-  Mode -->|high-risk or hard to reverse| Strict[strict-workflow mode<br/>stronger gates]
-
-  Workflow --> Entry{Choose entry point}
-  Strict --> Entry
-
-  Entry --> Discovery[Discovery<br/>discover<br/>interview-gate]
-  Entry --> Spec[Spec<br/>write-spec<br/>review-artifact]
-  Entry --> Plan[Plan<br/>write-plan<br/>review-artifact]
-  Entry --> Build[Build, diagnose, or TDD<br/>execute-plan<br/>diagnose-failure]
-  Entry --> Closeout[Closeout<br/>review-work<br/>verify-work<br/>commit-work]
-
-  Discovery --> Spec
-  Spec --> Plan
-  Plan --> Build
-  Build --> Closeout
-  Closeout --> Handoff[handoff<br/>durable checkpoint when needed]
-  Handoff --> Done
-
-  Reenter[Re-enter discovery<br/>new evidence, owner decision,<br/>source conflict, or failed check]
-  Spec -.-> Reenter
-  Plan -.-> Reenter
-  Build -.-> Reenter
-  Closeout -.-> Reenter
-  Handoff -.-> Reenter
-  Reenter --> Discovery
-
-  Bypass[bypass<br/>skip ceremony, not judgment] -.-> Entry
-```
-
-## Common Entry Points
-
-- Use `conversation mode` when the user asks a question, wants critique, or is doing non-mutating exploration or planning in chat. If the user asks to edit, create files, run mutating commands, commit, push, or otherwise change repo/system state, require `workflow` or `strict-workflow` before acting.
-- Use `discover` when repo, domain, evidence, current facts, brainstorming, targeted questions, or a decision checkpoint are needed before spec, plan, build, or durable memory.
-- Use `interview-gate` when direction is vague, source truth conflicts, or user-owned decisions are still open.
-- Use `write-spec` when requirements are agreed but not durable.
-- Use `review-artifact` when a spec, plan, handoff, or decision note must guide future work.
-- Use `write-plan` when an approved spec or explicit task context exists.
-- Use `execute-plan` when an approved plan exists; method skills like TDD run inside that build phase when requested or appropriate.
-- Use `diagnose-failure` when behavior is broken, failing, flaky, slow, or unclear.
-- Use `review-work` and `verify-work` before claiming consequential work is ready.
-- Use `commit-work` only after the intended diff is reviewed and verification evidence exists.
-- Use `handoff` when pausing, compacting, or transferring context.
-- Use `bypass` only to skip unnecessary ceremony. It cannot skip user-owned decisions, source-truth conflicts, risky checks, or verification claims.
-
-## Route Closeout
-
-Use `Next:` when naming the next route helps the user, not only when a workflow phase changes. Do not force it onto every reply.
-
-Completed consequential work and phase exits should include `Next:` unless the reply is only a direct answer, mid-task status, clarification-only turn, or direct owner-decision question.
-
-- Forward: name the next action or entry point, such as `write-spec`, `write-plan`, `execute-plan`, `review-work`, `verify-work`, `commit-work`, or `handoff`.
-- Backward: return to `interview-gate`, `discover`, `diagnose-failure`, or plan/spec revision when evidence, failed checks, or repeated review findings change the path.
-- Branch: show 2-3 valid next routes or actions when more than one is reasonable.
-- Stop: say no useful next action remains.
-
-After completed discovery with decisions that must survive beyond chat, prefer `write-spec`, an owning decision artifact, or handoff before planning or execution.
-
-Do not create the next artifact or take the next action just because it is the next route.